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PREFACE 



This publication describes how to 
compile a COBOL program using the Program 
Product IBH DOS/VS COBOL Compiler. It also 
describes how to link edit the resulting 
object module, and execute the program. 
Included is a description of the output 
from each of these three steps: compile, 
link edit, and execute. This publication 
explains features of the DOS/VS Compiler 
and Library, and available options of the 
operating system. 



This publication is logically and 
functionally divided into four parts. Part 
I contains information useful to 
programmers who are running COBOL programs 
compiled on the DOS/VS Compiler, under the 
control of the IBM Disk Operating System 
Virtual Storage. Part I covers such topics 
as job control language, library usage, and 
interpreting output. 

Part II contains supplemental 
information on the use of the language as 
specified in the publication IBM DOS Full 
American National Standard COBOL , 
GC28-6394, and should be used in 
conjunction with this publication for 
coding COBOL programs. Part II covers 
in detail such topics as file organization, 
file label handling, and record formats. 
Part II is intended as reference material 
for language features that are primarily 
system-dependent . 

Part III contains information on 
programming techniques useful to the 
programmer running COBOL programs compiled 
on the DOS/VS Compiler. Topics such as 
coding considerations, table handling 
considerations, and formatting data are 
covered in Part III. 

Part IV contains error determination 
information. This part covers such topics 
as program debugging and program testing . 

Diagnostic messages generated by the 
DOS/VS Compiler and Library and their 
accompanying documentation can be found in 
this publication. 

Information on installing the DOS/VS 
Compiler and Library can be found in the 
following publication: 

IBM DOS/VS COBOL Compiler and Library, 
Installation Reference Material , 
SC28-6479 

Wider ranging and more detailed 
discussions of the DOS/VS System are given 
in the following publications: 



Introduction to DOS/VS , 
GC33-5370 

DOS/VS System Generation , 
GC33-5377 

DOS/VS System Management Gu i de , 
GC33-5371 

DOS/VS Data-Management-Concepts , 
GCi4-SlSS 

DOS/VS Supervisor and I/O Macro 
Reference, GC33-5373 

DOS/VS System Control Statements , 
GC33-5376 

DOS/VS Access Method Service s, 
GC33-5382 

DOS/VS System Utilities Reference , 
GC33-5381 

DOS/VS Messages , GC33-5379 

The following publications provide 
detailed information on the IBM 3886 
Optical Character Reader: 

IBH 3886 Optical Character Reader 
General Information Manual , 
GA21-9146 

IBM 3886 Optical Character R eader Input 
Document Design and Specifications , 
GA21-9148 

DOS/VS Planning Guide for the IBM 3886 
Optical Character Reader, Model 1 , 
GC21-5059 

The following publications provide 
information on the IBM DOS/VS Sort/Merge 
Program Product, Program Number 5746-SMl, 
and the DOS Sort/Merge Program Product, 
Program Number 574 3-SMl: 

IBM DOS/VS sort/Merge Genera l 
Information , GC33-4030 

IBM DOS/YS Sort /Merge Program Product 
Design Objectiv es, GC33-4027 

IBH DOS/VS Sort/Merge Installation 
Reference Material , SC33-4026 

IBH DOS Sort/Merge Programmer's Guide , 
SC33-4018 

The titles and abstracts of related 
publications are listed in IBH Svstem/360 
and SYstem/370 Bibliography , GA22-6822. 



Summary of Amendments Number 5 



Form of Publication: Revision SC28-6478-3 

New: Programming Function 

Support for fixed block devices is provided under DOS/VSE with 
VSE/ Advanced Function, Release 1 . 

Maintenance: Documentation 

Clarifications and corrections have been made in various areas 
of the text. 



Editorial changes that have no technical significance are not noted here. 

Specific changes to the text made as of this publishing date are indicated hy a vertical bar to the 
left of the text. These bars will be deleted at any subsequent republication of the page affected. 



Summary of Amendments Number 4 



Form of Publication: TNL SN20-9235 to SC28-6478-0, -1 , -2 

New: Programming Function 

Support has been added for the 3330-1 1 Disk Storage and 3350 
Direct Access Storage devices. 

Maintenance: Documentation 

Minor technical changes and additions have been made to 
the text. 



Summary of Amendments Number 3 

Date of Publication: December 3, 1976 

Form of Publication: TNL SN20-9 180 to SC28-6478-0, -1 , -2 

IBM DOSA^S COBOL 

Maintenance: Documentation 

Minor technical changes and additions have been made to 
the text. 



Ivditorial changes that have no technical significance are not noted here. 

Specific changes to the text made as of this publishing date are indicated by a vertical bar to the 
left of the text. These bars will be deleted a( any subsequent republication of the page affected. 



Summary of Amendments Number 2 

Date of Publication: January 9, 1976 

Form of Publication: SN20-9141 to SC28-6478-0, -1 

Support has been added to run DOS/VS COBOL under control of VM/370 CMS Release 3. 

DOS/VS COBOL programs can be compiled in CMS and then executed in a DOS virtual machine, or 
under a DOS system. 

The following restrictions apply to execution of DOS/VS COBOL programs in CMS: 

1. Indexed files (DTFIS) are not supported. Various clauses and statements are therefore invalid: 
RECORD KEY, APPLY CYL-OVERFLOW, NOMINAL KEY, APPLY MASTER/CYL-INDEX, 
TRACK-AREA, APPLY CORE-INDEX, and START. 

2. Creating direct files is restricted as follows: 

—For U or V recording modes, access mode must be sequential. 

-For ACCESS IS SEQUENTIAL, track identifier must not be modified. 

3. None of the user label-handling functions are supported. Therefore, the label-handling format of 
USE is invalid. The data-name option of the LABEL RECORDS clause is invalid. 

4. There is no Sort or Segmentation feature. 

5. ASCII-encoded tape files are not supported. 

6. Spanned records (S-mode) processing is not available. This means that the S-mode default (block 
size smaller than record size) cannot be specified, and that the RECORDING MODE IS S clause 
cannot be specified. 

In addition, multitasking, multipartition operation, and teleprocessing functions are not supported 
when executing under CMS. 

For a more detailed description of VM/370 CMS for DOS/VS COBOL, see IBM VM/370 CMS User's 
Guide for COBOL, order number SC28-6469. 

Summary of Amendments Number 1 



Date of Publication: March 22, 1974 

Form of Publication: TNL SN28-1063 to SC28-6478-0 



New: Additional Compiler Capabilities 

Lister feature 
Execution Statistics and 
Verb summary feature 

SORT-OPTION 



Maintenance: Documentation Only 

Minor technical changes and corrections. 



Editorial changes that have no technical significance are not noted here. 

Specific changes to the text made as of this publishing date are indicated by a vertical bar to the 
left of the text. These bars will be deleted at any subsequent repubUcation of the page affected. 
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FEATURES OF THE PROGRAM PRODUCT DOS/VS COMPILER 



The IBM DOS/VS COBOL Compiler includes 
the following features: 

• Object Code ; 

(1) Optimized Object Code — which 
results, when specified, in up to 
30% space saving in object program 
generated code and global tables 
as compared with Version 2 of the 
IBM DOS Full American National 
Standard COBOL Compiler, The 
space saved depends on the number 
of referenced procedure-names and 
branches, and on 01- level data 
names. 

(2) Double-Buffered ISAM — allows 
faster sequential processing of 
indexed files. 

(3) The MOVE Statement and Comparisons 
— when a MOVE statement or a 
comparison involves a one-byte 
literal, generated code for the 
move and the comparison saves 
object program space and 
compilation time. 

(4) DISPLAY Routines — the DISPLAY 
routine has been split into 
subsets for efficient object 
program code. 

• Alphabetized Cross-Ref erence Listing 
(SXREF) — for easier reference to 
user-specified names in a program. 
SXREF performs up to 25 times faster 
than the source-ordered cross-reference 
(XREF) feature of Version 2 of the IBM 
DOS Full American National Standard 
COBOL Compiler. The larger the source 
program, the more that performance is 
improved. Total compilation time is up 
to 2 times faster. 

• Debugging Facilities ; 

(1) Symbolic Debug Feature — which 
provides a symbolic formatted dump 
at abnormal termination, or a 
dynamic dump during program 
execution. 

(2) Flow Trace Option — a formatted 
trace can be requested for a 
variable number of procedures 
executed before abnormal 
termination . 

(3) Statement Number Option — 
identifies the COBOL statement 
being executed at abnormal 
termination. 



(U) Expanded CLIST and SYM — for 
detailed information about the 
Data Division and Procedure 
Division. 

(5) Relocation Factor — can be 
requested to be included in 
addresses on the object code 
listing, for easier debugging. 

(6) Working-Storage Location and Size 
— When CLIST and SYM are in 
effect, the starting address and 
size of Working- Storage are 
printed. 

(7) Syntax-Check Feature — optionally 
provides a quick scan of the 
source program without producing 
object code. Syntax checking can 
be conditional or unconditional. 

(8) WHEN-COMPILED Special Register -- 
makes the date-and-time- compiled 
constant carried in the object 
module available to the object 
program. This special register is 
a programmer aid that provides a 
means of associating a compilation 
listing with both the object 
program and the output produced at 
execution time. 

• Device Support — the following devices 
can be specified in addition to devices 
supported by the IBM DOS Full American 
National Standard COBOL compilers: 

5203,3203 — line printers 

3211 — 150-character printer 

3330,3340,3350 — mass storage 
(direct access) facilities 

Fixed block direct access storage 
devices 

35U0 — Diskette input/output unit 

3410,3420 — tape utility devices 

256 0,3504,3505,3525,3881,3886,5425 — 
advanced unit-record devices 

• ASCII Suppor t — allows creation and 
retrieval of tape files written in the 
American National standard Code for 
Information Interchange (ASCII). 

• VSAM (Virtual Storage Access Method) 
Support — provides fast storage and 
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retrieval of records, password 
protection, centralized and simplified 
data and space management, advanced 
error recovery facilities, plus system 
catalog. COBOL supports indexed 
(key-sequenced) files and sequential 
(entry- sequenced) files. Records can 
be fixed or variable in length. 

• FIPS (Federal Information Processing 
Standard) Flagger — issues messages 
identifying nonstandard elements in a 
COBOL source program. The FIPS Flagger 
makes it possible to ensure that COBOL 
clauses and statements in a DOS/VS 
COBOL source program conform to the 
Federal Information Processing 
Standard. 

• Lister — provides a specially 
formatted source listing with embedded 
cross-references for increased 
intelligibility and ease of use. A 
reformatted source deck is available as 
an option. 

• Generic Key Facility for ISAM Files — 
sequential record retrieval can be 



requested using a search argument 
comprised of a user-specified number of 
high-order characters (generic portion) 
of the NOMINAL KEY. The user need not 
specify a full or exact search key. 
This feature is supported via the START 
verb. 



• MERGE Support — combines from two to 
eight identically sequenced files on a 
set of specified keys and makes records 
available, in merged order, to an 
output procedure or a sequential output 
file- 

• Verb profiles — facilitates 
identifying and locating verbs in the 
COBOL source program. Options provide 
a verb summary or a verb 
cross-reference listing which includes 
the verb summary. 

• Execution- time statistics — maintains 
a count of the number of times each 
verb in the COBOL source progrdm is 
executed during an individual program 
execution. 
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COBOL has undergone considerable 
refinement and standardization since 1959- 
A standard COBOL has been approved by the 
American National Standards Institute, an 
industry-wide association of computer 
manufacturers and users. This standard is 
called American National Standard COBOL. 
IBM Full American National Standard COBOL 
is compatible with American National 
Standard COBOL and includes a number of 
extensions to it as well. 
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statements. Job control statements 
describe the jobs to be performed and 
specify the programmer's requirements for 
each job. Job control statements are 
written by the programmer using the job 
control language. The use of job control 
statements and the rules for specifying 
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INITIAL PROGRAM LOADER 



An IBM COBOL program may be processed by 
the IBM DOS/VS System. Under control of 
the operating system, a set of COBOL source 
statements is translated to form a module . 
In order to be executed, the module in turn 
must be processed to form a phase . The 
reasons for this will become clear later. 
For now it is sufficient to note that the 
flow of a COBOL program through the 
operating system is from source statements 
to module to phase. 

The DOS/VS System consists essentially 
of a control program and a number of 
processing programs , and data management . 



CONTROL PROGRAM 



The Initial Program Loader (IPL) routine 
loads the Supervisor into storage when 
system operation is initiated. Detailed 
information about the Initial Program 
Loader need not concern the COBOL 
programmer. Anyone interested in this 
material, however, can find it in the 
publication DOS/VS System Mana g ement Guide . 



PROCESSING PROGRAMS 



The processing programs include the 
COBOL compiler, service programs, and 
application programs. 



The components of the control program 
are: the Supervisor, Job Control 
Processor, and the Initial Program Loader. 



SUPERVISOR 



The main function of the Supervisor is 
to provide an orderly and efficient flow of 
jobs through the operating system. (A job 
is some specified unit of work, such as the 
processing of a COBOL program.) The 
Supervisor loads into the computer the 
phases that are to be executed. During 
execution of the program, control usually 
alternates between the Supervisor and the 
processing program. The Supervisor, for 
example, handles all requests for 
input/output operations. 



JOB CONTROL PROCESSOR 



The primary function of the Job Control 
Processor is the processing of job control 



SYSTEM SERVICE PROGRAMS 



The system service programs provide the 
functions of generating the system, 
creating and maintaining the library 
sections, and editing programs into disk 
residence before execution. The system 
service programs are: 

1. Linkage Edito r. The Linkage Editor 
processes modules and incorporates 
them into phases. A single module can 
be edited to form a single phase, or 
several modules can be edited or 
linked together to form one executable 
phase. Moreover, a module to be 
processed by the Linkage Editor may be 
one that was just created (during the 
same job) or one that was created in a 
previous job and saved. 

The programmer instructs the Linkage 
Editor to perform these functions 
through job control statements. In 
addition, there are several linkage 
editor control statements. 
Information on their use is given 
later. 
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Librarian . The Librarian consists of 
a group of programs used for 
generating the system, maintaining and 
reorganizing the disk library areas, 
and providing printed and punched 
output from the libraries. The system 
libraries are: the core image 
library, the relocatable library, the 
source statement library, and the 
procedure library. In addition, the 
Librarian supports private core image, 
relocatable, and source statement 
libraries. Detailed information on 
the Librarian is given later. 



program concurrently by interleaving their 
execution. This support is referred to as 
fixed partitioned multiprogramming, since 
the virtual address space is divided into a 
fixed number of partitions. Each program 
occupies a contiguous area of storage. The 
amount of virtual storage allocated to 
programs to be executed may be determined 
when the system is generated, or it may be 
determined by the operator when the program 
is loaded into storage for execution. 



APPLICATION PROGRAMS 



BACKGROUND VS. FOFEGPOUND PROGRAMS 



Application programs are usually 
programs written in a higher-level 
programming language (e.g., COBOL), 
application programs within the Disk 
Operating System/Virtual Storage are 
executed under the supervision of the 
control program. 



IBH-SOPPLIED PROCESSING PROGRAMS 



All 



There are two types of problem programs 
in multiprogramming: background and 
foreground. Background and foreground 
programs are initiated by the Job Control 
Processor from batched-job input streams. 



Background and foreground programs 
initiate and terminate independently of one 
another. Neither is aware of the other's 
status or existence. 



The following are examples of 
IBM-supplied processing programs: 

1. Language translators, e.g., DOS/VS 
COBOL, which translate source programs 
written in various languages into 
machine (or object) language. 

2. Sort/Merge 

3. Utilities 



DATA MANAGEMENT 



A third important class of components is 
data management routines. These are 
available for inclusion in problem programs 
to relieve the programmer of the detailed 
programming associated with the transfer of 
data between programs and auxiliary 
storage. 



MULTIPROGRAMMING 



Multiprogramming refers to the ability 
of the system to control more than one 



The system is capable of concurrently 
operating one background program and four 
foreground programs. Priority for CPU 
processing is controlled by the Supervisor 
with foreground programs normally having 
priority over background programs. Control 
is taken away from a high priority program 
when that program encounters a condition 
that prevents continuation of processing, 
until a specified event has occurred. 
Control is taken away from a lower priority 
program when an event for which a higher 
priority program was waiting has been 
completed. Interruptions are received and 
processed by the Supervisor. 

In a multiprogramming environment, the 
DOS/VS COBOL compiler can execute either in 
the background or the foreground. In 
systems that support the batched-job 
foreground and private core image library 
options, the Linkage Editor can execute in 
any foreground partition as well as in the 
background partition. To execute the 
DOS/VS COBOL compiler for the linkage 
editor in any foreground partition, a 
private core-image library is reguired. 
Additional information on executing the 
compiler and Linkage Editor in the 
foreground is contained in "Appendix F: 
System and Size Considerations." COBOL 
program phases can be executed as either 
background or foreground programs. 
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JOB DEFINITION 



A -job is a specified unit 
performed under control of th 
system. A typical job might 
processing of a COBOL program 
source statements, editing th 
produced to form a phase, and 
executing the phase. Job def 
process of specifying the wor 
during a single job — allows 
programmer considerable flexi 
can include as many or as few 
the programmer desires. 



JOB STEPS 



of work to be 
e operating 
be the 

— compiling 
e module 

then 
inition — the 
k to be done 

the 
bility . A job 

job steps as 



steps: (1) compile (main program) , (2) 
compile (first subprogram) , (3) compile 
(second subprogram) , (4) link edit (three 
modules combined into one phase) , and (5) 
execute (phase) . Figure 1 shows a sample 
structure of the job deck for these five 
job steps. Compilation and execution in 
three job steps — compile, link edit, and 
execute — is applicable only when the 
COBOL source program is a single main 
program. 




I// JOB PP0G1 



A job step is exactly what the name 
implies — one step in the processing of a 
job. Thus, in the job mentioned above, one 
job step is the compilation of source 
statements; another is the link editing of 
a module; another is the execution of a 
phase. In contrast to a job definition, 
the definition of a job step is fixed. 
Each job step involves the execution of a 
program, whether it be a program that is 
part of the Disk Operating System/Virtual 
Storage or a program that is written by the 
programmer. A compilation requires the 
execution of the DOS/VS COBOL compiler. 
Similarly, an editing implies the execution 
of the Linkage Editor Finally, the 
execution of a phase is the execution of 
the problem program itself. 



I// EXEC FCOBOL 

(source deck 
I/* 



main program} 



I// EXEC FCOBOL 

{source deck - first subprogram} 
I/* 



I// EXEC FCOBOL 

(source deck - second subprogram} 
I/* 



I// EXEC LNKEDT 



Compilation Job Steps 



The compilation of a COBOL program may 
necessitate more than one job step (more 
than one execution of the DOS/VS COBOL 
compiler) . In some cases, a COBOL program 
consists of a main program and one or more 
subprograms. To compile such a program, a 
separate job step must be specified for the 
main program and for each of the 
subprograms. Thus, the DOS/VS COBOL 
compiler is executed once for the main 
program and once for each subprogram. Each 
execution of the compiler produces a 
module. The separate modules can then be 
combined into one phase by a single job 
step — the execution of the Linkage 
Editor. 

For a COBOL program that consists of a 
main program and two subprograms, 
compilation and execution reguire five 



I// EXEC 



Figure 1. Sample Structure of Job Deck 
for Compiling, Link Editing, 
and Executing a Main Program 
and Two Subprograms 



Multiphase Program Executio n 



The execution of a COBOL program has 
thus far been referred to as the execution 
of a phase. It is possible, however, to 
organize a COBOL program so that it is 
executed as two or more phases. Such a 
program is known as a multiphase program . 

By definition, a phase is that portion 
of a program that is loaded into virtual 
storage by a single operation of the 
Supervisor. A COBOL program can be 
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executed as a single phase only if there is 
an area of virtual storage available to 
accommodate all of it. A program that is 
too large to be executed as a single phase 
must be structured as a multiphase program. 
The technique that enables the programmer 
to use subprograms that do not fit into 
virtual storage (along with the main 
program) is called overlay . 

The number of phases in a COBOL program 
has no effect on the number of job steps 
required to process that program. As will 
be seen, the Linkage Editor can produce one 
or more phases in a single job step. 
Similarly, both single-phase and multiphase 
programs require only one execution job 
step. Phase execution is the execution of 
all phases that constitute one COBOL 
program . 

Detailed information on overlay 
structures, as well as information on using 
the facilities of the operating system to 
create multiple phases and to execute them, 
can be found in the chapter "Calling and 
Called Programs." 



Compile and Edit : This type of job 
combines the functions of the compile-only 
and the edit-only jobs. It requires the 
execution of both the COBOL compiler and 
the Linkage Editor. The job can include 
one or more compilations, resulting in one 
or more modules. The programmer can 
specify that the Linkage Editor process any 
or all of the modules just produced; in 
addition, he can specify that one or more 
previously produced modules be included in 
the linkage editor processing. 



Execute-Onli 



This type of job involves 



the execution of a phase (or multiple 
phases) produced in a previous job. Once a 
COBOL program has been compiled and edited 
successfully, it can be retained as one or 
more phases and executed whenever needed. 
This eliminates the need for recompiling 
and re-editing every time a COBOL program 
is to be executed. 



TYPES OF JOBS 



Edit and Execute : This type of job 
combines the functions of the edit-only and 
the execute-only jobs. It requires the 
execution of both the Linkage Editor and 
the resulting phase (s) . 



A typical job falls into one of several 
categories. A brief description of these 
categories follows; a complete discussion 
is found in the chapter "Preparing COBOL 
Programs for Processing." 



Compile-Only : This type of job involves 
only the execution of the COBOL compiler. 
It is useful when checking for errors in 
COBOL source statements. A compile-only 
job is also used to produce a module that 
is to be further processed in a subsequent 
job. 

A compile-only job can consist of one 
job step or several successive job steps. 



Edit-Only : This type of job involves only 
the execution of the Linkage Editor. It is 
used primarily to combine modules produced 
in previous compile-only jobs, and to check 
that all cross references between modules 
have been resolved. The programmer can 
specify that all modules be combined to 
form one, phase; or he can specify that some 
modules ?orm one phase and that others form 
additional phases. The phase output 
produced as the result of an edit-only job 
can be retained for execution in a 
subsequent job. 



Compile, Edit, and Execute : This type of 
job combines the functions of the compile 
and edit and the execute-only jobs. It 
calls for the execution of the COBOL 
compiler, the Linkage Editor, and the 
problem program; that is, the COBOL program 
is to be completely processed. 

When considering the definition of his 
job, the programmer should be aware of the 
following: if a job step is cancelle d 
during execution, the entire job is 
terminated; an y remaining job steps are 
skipped . Thus, in a compile-edit-and 
execute job, a failure in compilation 
precludes the editing of the module (s) and 
phase execution. Similarly, a failure in 
editing precludes phase execution. 

For this reason, a job usually should 
(but need not) consist of related job steps 
only. For example, if two independent 
single-phase executions are included in one 
job, the failure of the first phase 
execution precludes the execution of the 
second phase. Defining each phase 
execution as a separate job would prevent 
this from happening. If successful 
execution of both phases can be guaranteed 
before the job is run, however, the d 
programmer may prefer to include both " 
executions in a single job. 



Mi 



JOB DEFINITION STATEMENTS 



Once the prograiraner has decided the work 
to be done within his job and how many job 
steps are required to perform the job, he 
can then define his job by writing job 
control statements. Since these statements 
are usually punched in cards, the set of 
job control statements is referred to as a 
job deck . In addition to job control 
statements, the job deck can include input 
data for a program that is executed during 
a job step. For example, input data for 
the COBOL compiler — the COBOL program to 
be compiled — can be placed in the job 
deck. 



The inclusion of input data in the job 
deck depends upon the manner in which the 
installation has assigned input/output 
devices. Job control statements are read 
from the trnit named SYSRDR (system reader) , 
which can be either a card reader, a 
magnetic tape unit, or a disk extent. 
Input to the processing programs is read 
from the unit named SYSIPT (system input), 
which also can be either a card reader, a 
magnetic tape unit, or a disk extent. The 
installation has the option of assigning 
either two separate devices for these units 
(one device for SYSRDR, a second device for 
SYSIPT) or one device to serve as both 
SYSRDR and SYSIPT. If two devices have 
been assigned, the job deck must consist of 
only job control statements; input data 
must be kept separate. If only one device 
has been assigned, input data must be 
included within the job deck. 



There are four job control statements 
that are used for job definition: the JOB 
statement, the EXEC statement, the 
end-of-data statement (/*) , and the 
end-of- job statement (/&) . In this 
chapter, the discussion of these job 
control statements is limited to the 
function and use of each statement. The 
rules for writing each statement are given 
in the chapter "Preparing COBOL Programs 
for Processing." 

The JOB stateraent indicates the 
beginning of control information for a job. 
The specified job name is stored in the 
communications region of the corresponding 
partition and is used by job accounting and 
to identify listings produced during 
execution of the job. 

The JOB statement may be om.itted, in 
which case the job name NONAME is stored in 
the communications region. If the JOB 
statement is present, it must contain a job 
name; otherwise, an error condition occurs. 



The JOB statement is always printed in 
positions 1 through 72 on SYSLST and 
SYSLOG. The time-of-day and date are also 
printed. The JOB statement causes a skip 
to a new page before printing is started on 
SYSLST. 

When a JOB statement is encountered, the 
job control program stores the job name 
from the JOB statement into the 
communications region. If the /& statement 
was omitted, the next JOB statement will 
cause control to be transferred to the 
end-of- job routine to simulate the /& 
statement. 



The EXEC statement requests the 
execution of a program. Therefore, one 
EXEC statement is required for each job 
step within a job. The EXEC statement 
indicates the program that is to be 
executed (for example, the COBOL compiler, 
the Linkage Editor) . As soon as the EXEC 
statement has been processed, the program 
indicated by the statement begins 
execution. 



The end-of-data statement, also referred 
to as the /* (slash asterisk) statement, 
defines the end of a program's input data. 
,When the data is included within the job 
deck (that is, SYSIPT and SYSRDR are the 
same device) , the /* statement immediately 
follows the input data. For example, COBOL 
source statements would be placed 
immediately after the EXEC statement for 
the COBOL compiler; a /* statement would 
follow the last COBOL source statement. 

Note: For an input file on a 5425 MFCU, 
the /♦ card must be followed by a blank 
card. 



When input data is kept separate (that 
is, SYSIPT and SYSRDR are separate 
devices) , the /* statement immediately 
follows each set of input data on SYSIPT. 
For example, if a job consists of two 
compilation job steps, an editing job step, 
and an execution job step, SYSIPT would 
contain the source statements for the first 
compilation followed by a /* statement, the 
source statements for the second 
compilation followed by a /* statement, any 
input data for the Linkage Editor followed 
by a /* statement, and perhaps some input 
data for the problem program followed by a 
/* statement. 



The end-of- job statement, also referred 
to as the /& (slash ampersand) statement, 
defines the end of the job. A /S statement 
must appear as the last statement in the 
job deck. 
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OTHER JOB CONTROL STATEMENTS 



The four job definition statements form 
the framework of the job deck. There are a 
number of other job control statements in 
the job control language; however, not all 
of them must appear in the job deck. The 
job control statements are summarized 
briefly in Table 1. 



The double slash preceding each 
statement name identifies the statement as 
a job control statement. Most of the 
statements are used for data management — 
creating, manipulating, and keeping track 
of data files . (Data files are externally 
stored collections of data from which data 
is read and onto which data is written. ) 



Table 1. Job Control Statements 
Function 



r T" 

I Statement | 



h 



// ASSGN 
// CLOSE 

// DATE 

// DLAB 
// DLBL 

// EXEC 
// EXTENT 
// JOB 

// LBLTYP 

// LISTIO 

// MTC 

// OPTION 

// PAUSE 

// RESET 



Input/output assignments. 

Closes a logical unit assigned 
to magnetic tape. 

Provides a date for the 
Communication Region. 

Disk file label information. 

Disk file label information 
and VSAM file processing. 

Execute program. 

Disk file extent. 

Beginning of control 
information for a job. 

Reserves storage for label 
information. 

Lists input/output 
assignments. 

Controls operations on 
magnetic tape. 

Specifies one or more job 
control options . 

Creates a pause for operator 
intervention . 

Resets input/output 

assignments to standard 
assignments. 



// 


RSTRT 


Restarts a checkpointed 
program. 


// 


TLBL 


Tape label information. 


// 


TPLAB 


Tape label information. 


// 


UPSI 


Sets user-program switches. 


// 


VOL 


Disk/tape label information. 


// 


XTENT 


Disk file extent. 


// 


ZONE 


Sets the zone for the date. 


/♦ 




End-of-data-f ile or 
end-of- job-step. 


/6 




End-of - job= 


♦ 





Comments. 

L 



JOB PROCESSING 



This chapter describes in greater detail 
the three types of job steps involved in 
processing a COBOL program. Once the 
reader becomes familiar with the 
information presented here, he should be 
able to write control statements by 
referring only to the next chapter, 
"Preparing COBOL Programs for Processing." 



COMPILATION 



Compilation is the execution of the 
COBOL compiler. The programmer requests 
compilation by placing in the job deck an 
EXEC statement that contains the program 
name FCOBOL, the name of the DOS/VS COBOL 
compiler. This is the EXEC FCOBOL 
statement. If the compiler is loaded 
from a user program, that program must be 
a cataloged phase. The name of the phase 
must have as its first four characters 
' FCOB • . 



EDITING 



Editing is the execution of the Linkage 
Editor. The programmer reguests editing by 
placing in the job deck an EXEC statement 
that contains the program name LNKEDT, the 
name of the Linkage Editor. This is the 
EXEC LNKEDT statement. 

Input to the Linkage Editor consists of 
a set of linkage editor control statements 
and one or more modules to be edited. 
These modules include any of the following: 

1. Modules that were compiled previously 
in the job and placed at that time on 
the linkage editor input unit, SYSLNK. 

2. Modules that were compiled in a 
previous job and saved as module 
decks. The module decks must be 
placed on SYSIPT. Linkage editor 
control statements are read from 
SYSRDR. 




Input to the compiler is a set of COBOL 
source statements, consisting of either a 
main program or a subprogram. Source 
statements must be punched in Extended 
Binary-Coded-Decimal Interchange Code 
(EBCDIC) . The COBOL source statements are 
read from SYSIPT. The job deck is read 
from SYSRDR. If SYSEDE and SYSIPT are 
assigned to the same unit, the COBOL source 
statements should be placed after the EXEC 
FCOBOL statement in the job deck. 

Output from the COBOL compiler is 
dependent upon the options specified when 
the system is generated. This output may 
include a listing of source statements 
exactly as they appear in the input deck. 
The source listing is produced on SYSLST. 
In addition, the module produced by the 
compiler may be written on SYSLNK, the 
linkage editor input unit, and punched on 
SYSPCH. Separate Data and/or Procedure 
Division maps, a symbolic cross-reference 
list, and diagnostic messages can also be 
produced. The format of compiler output is 
discussed and illustrated in the chapter 
"Interpreting Output." 

The programmer can override any of the 
compiler options specified when the system 
was generated, or include some not 
previously specified, by using the OPTION 
control statement in the compile job step. 
Compiler options are discussed in detail in 
the chapter "Preparing COBOL Programs for 
Processing." 



3. Modules that were compiled in a 

previous job step and cataloged in the 
relocatable library . The relocatable 
library is a collection of frequently 
used routines in the form of modules, 
that can be included in a program 
phase via the INCLUDE control 
statement in the linkage editor job 
step. 

Output from the Linkage Editor consists 
of one or more phases. A phase may be an 
entire program or it may be part of an 
overlay structure (multiple phases) . 

A phase produced by the Linkage Editor 
can be executed immediately after it is 
produced (that is, in the job step 
immediately following the linkage editor 
job step) , or it can be executed later, 
either in a subseguent job step of the same 
job or in a subsequent job. In either of 
the latter cases, the phase to be executed 
must be cataloged in the core image libary* 
Such a phase can be retrieved in the 
execute job step by specifying the phase 
name in the EXEC statement, where phase 
name is the name under which it was 
cataloged. Otherwise, the phase output is 
retained only for the duration of one job 
step following the linkage editor job step. 
That is, if the module that was just link 
edited is to be executed in the next job 
step, it need not have been cataloged. An 
EXEC statement will cause the phase to be 
brought in from the temporary part of the 
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core image library and will begin 
execution. However, the next time such a 
module is to be executed, the linkage 
editor job step is required since the phase 
was not cataloged in the core image 
library. 

If a private core image library is 
assigned, output from the Linkage Editor is 
placed in the private core image library 
(either permanently or temporarily) rather 
than in the resident system core image 
library. When execution of a program is 
requested and a private core image library 
is assigned, this library is searched first 
for the requested phase name and then the 
system core image library is searched. 

In addition to the phase, the Linkage 
Editor produces a phase map on SYSLST. 
Linkage editor diagnostic messages are also 
printed on SYSLST. If the NOHAP option of 
the linkage editor ACTION control statement 
is specified, no phase map is produced and 
linkage editor diagnostic messages are 
listed on SYSLST, if assigned. Otherwise, 
the diagnostic messages are listed on 
SYSLOG. The contents of the phase map are 
discussed and illustrated in the chapter 
"Interpreting Output.** 

Linkage editor control statements direct 
the execution of the Linkage Editor. 
Together with any module decks to be 
processed, they form the linkage editor 
input deck , which is read by the Job 
Control Processor from SYSIPT and written 
on SYSLNK. 

There are four linkage editor control 
statements: the ACTION statement, the 
PHASE statement, the ENTRY statement, and 
the INCLUDE statement. These statements 
are discussed in the next chapter. 



PHASE EXECUTION 



Phase execution is the execution of the 
problem program, for example, the program 
written by the COBOL programmer. If the 
program is an overlay structure (multiple 
phase) , the execution job step actually 
involves the execution of all the phases in 
the program. 



The phase (s) to be executed must be 
contained in the core image library . The 
core image library is a collection of 
executable phases from which programs are 
loaded by the Supervisor. A phase is 
written in the temporary part of the core 
image library by the Linkage Editor at the 
time the phase is produced . It is 
permanently retained (cataloged) in the 
core image library, if the programmer has 
so requested, via the CATAL option in the 
OPTION control statement. 

The programmer requests the execution of 
a phase by placing in the job deck an EXEC 
statement that specifies the name of the 
phase. However, if the phase to be 
executed was produced in the immediately 
preceding job step, it is not necessary to 
specify its name in the EXEC statement. 



MULTIPHASE PROGRAMS 



A COBOL program can be executed as a 
single phase as long as there is an area of 
virtual storage available to accommodate 
it. This area, known as the problem 
program area , must be large enough to 
contain the main program and all called 
subprograms. When a program is too large 
to be executed as a single phase, it must 
be structured as a multiphase program. 

The overlay structure available to the 
COBOL programmer for multiphase programs is 
known as root phase overlay , and is used 
primarily for programs of three or more 
phases. One phase of the program is 
designated as the root phase (main program) 
and, as such, remains in the problem 
program area throughout the execution of 
the entire program. The other phases in 
the program — subordinate phases — are 
loaded into the problem program area as 
they are needed. A subordinate phase may 
overlay any previously loaded subordinate 
phase, but no subordinate phase may overlay 
the root phase. One or more subordinate 
phases can reside simultaneously in storage 
with the root phase. 

Use of the linkage editor control 
statements needed to effect overlay are 
discussed in the chapter "Calling and 
Called Programs." 



{ 



PREPARING COBOL PROGRAMS FOR PROCESSING 



This chapter provides information about 
preparing COBOL source programs for 
compilation, link editing, and execution. 



ASSIGNMENT OF INPUT/OUTPUT DEVICES 



Almost all COBOL programs include 
input/output statements calling for data to 
be read from or written into data files 
stored on external devices. COBOL programs 
do not reference input/output devices by 
their actual physical address, but rather 
by their symbolic names. Thus, a COBOL 
program is dependent on the device type but 
not on the actual device address- Using 
VSAM, it is not even dependent on the 
device type. The COBOL programmer need 
only select the symbolic name of a device 
from a fixed set of symbolic names. At 
execution time, as a job control function, 
the symbolic name is associated with an 
actual physical device. The standard 
assignment of physical addresses to 
symbolic names may be made at system 
generation time. However, job control 
statements and operator commands can alter 
the standard device assignment before 
program execution. This is discussed later 
in this chapter. 

Using IX)S/VS, a logical unit may also be 
assigned to another logical unit or a 
general device class or specific device 
type. For more information on this, see 
DOS/VS System Management Guide and DOS/VS 
System Control Statements . 

The symbolic names are divided into two 
classes: system logical units and 
programmer logical units . 



The system logical units are used by the 
control program and by IBM-supplied 
processing programs. SYSIPT, SYSLST, 
SYSPCH, and SYSLOG can be implicitly 
referenced by certain COBOL procedural 
statements. Two additional names, SYSIN 
and SYSOUT, are defined for background 
program assignments- The names are valid 
only to the Job Control Processor, and 
cannot be referenced in the COBOL program. 
SYSIN can be used when SYSRDR and SYSIPT 
are the same device; SYSOUT must be used 
when SYSLST and SYSPCH are assigned to the 
same magnetic tape unit. A complete 
discussion of the assignment of the logical 
unit SYSCLB can be found in the publication 
DOS/VS System Control Statements . 



Programmer logical units are those in 
the range SYSOOO through SYS240 (depending 
on the number of partitions in the system) 
and are referred to in the COBOL source 
language ASSIGN clause. 



A COBOL programmer uses the source 
language ASSIGN clause to assign a file 
used by his problem program to the 
appropriate symbolic name. Although 
symbolic names may be assigned to physical 
devices at system generation time, the 
programmer may alter these assignments at 
execution time by means of the ASSGN 
control statement. However, if the 
programmer wishes to use the assignments 
made at system generation time for his own 
data files in the COBOL program, ASSGN 
control statements are unnecessary. 

Table 2 is a complete list of symbolic 
names and their usage. 
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Table 2. Symbolic Names, Functions, and Permissible Device Types 

I 1 1 



1 Symbolic | Function I Permissible | 
IName | | Device Types | 


ISYSRDR 1 Input unit for control statements or commands. | Card reader | 
1 1 1 Magnetic Tape unit | 
! 1 1 Disk extent | 
1 1 1 3540 diskette | 


ISYSIPT 1 Input unit for programs. I Card reader | 
1 1 1 Magnetic tape unit | 
1 1 1 Disk extent | 
i i ! 35U0 diskette j 


ISYSPCH IMain unit for punched output. | Card punch | 
i i ! Magnetic tape unit | 
1 1 1 Disk extent | 
1 1 1 3540 diskette | 


ISYSLST jflain unit for printed output. | Printer I 
1 1 1 Magnetic tape unit | 
1 1 1 Disk extent | 
1 1 1 3540 diskette | 


jSYSLOG 1 Receives operator messages and logs in job control | Printer keyboard | 
1 [statements. | Printer I 
1 1 1 Display operator console! 


ISYSLNK 1 Input to the Linkage Editor. I Disk extent | 


jSYSRES 1 Contains the operating system, the core image | Disk extent | 
1 1 library, relocatable library, source statement | I 
1 1 library, and procedure library. I | 


ISYSCLB |A private core image library. I Disk extent | 


ISYSSLB |A private source statement library. | Disk extent | 


isYSRLB |A private relocatable library. | Disk extent | 


ISYSIH IMust be used when SYSRDR and SYSIPT are assigned to| Disk I 
1 |the same disk extent. May be used when they are | Magnetic tape unit I 
1 jsame disk extent. May be used when they are | Card reader | 
1 1 assigned to the same card reader or magnetic tape. | 3540 Diskette | 


ISYSOUT IThis name must be used when SYSPCH and SYSLST are | Magnetic tape unit | 
1 1 assigned to the same magnetic tape unit. It must | I 
1 |be assigned by the operator ASSGN command. | I 


ISYSmax | These units are available to the programmer as work 1 Any unit I 
1 1 files or for storing data files. They are called | I 
1 1 programmer logical units as opposed to the above- 1 1 


1 1 mentioned names which are always referred to as | 1 
! [system logical units. The largest number of 1 1 


1 [programmer logical units available in the system is| [ 
[ [240 {SYSOOO through SYS240, depending on number of [ I 
[ [partitions). The value of SYSmax is determined by | I 
1 [the distribution of the programmer logical units | 1 
1 [among the partitions. j 1 


[SYSVIS [Holds virtual storage page data set. [ Disk extent I 


[SYSCAT [Holds the VSAH catalog. I Disk extent [ 


[SYSREC [Logs error records. I Disk extent [ 
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JOB CONTPOL 



The Job Control Processor for the Disk 
Operating System/Virtual Storage prepares 
the system for execution of programs in a 
batched job environment. Input to the Job 
Control Processor is in the form of job 
control statements and job control 
commands . 



in the job deck. The remainder of the card 
may contain any character from the EBCDIC 
set. Comment statements are designed for 
communication with the operator; 
accordingly, they are written on the 
console output unit, SYSLOG, in addition to 
being written on SYSLST. If followed by a 
PAUSE control statement, the comment 
statement can be used to request operator 
action . 



JOB CONTROL STATEMENTS 



Job control statements are designed for 
an 80-column punched card format. Although 
certain restrictions must be observed, the 
statements are essentially free form. Job 
control statements conform to these rules: 



Statement Formats 



The following notation is used in the 
statement formats: 



1. Name . Two slashes (//) identify the 
statement as a job control statement, 
■^hey must be in coluans 1 and 2. At 
least one blank immediately follows 
the second slash. 

Exceptions : The end-of-job statement 
contains /& in columns 1 and 2; the 
end-of-data-f ile statement contains /♦ 
in columns 1 and 2; the comment 
statement contains * in column 1 and a 
blank in column 2. 

2. Operation . This identifies the 
operation to be performed. It can be 
up to eight characters long. At least 
one blank follows its last character. 

3- Operand . This may be blank or may 

contain one or more entries separated 
by commas. The last term must be 
followed by a blank, unless its last 
character is in column 71. 

U. Comment s. Optional programmer 

comments must be separated from the 
operand by at least one space. 

Continuation cards are not recognized by 
the Job Control Processor. For the 
exception to this rule, see the 
descriptions of the DLAB and TPLAB 
statements. 

All job control statements are read from 
the device identified by the symbolic name 
SYSRDE. 



All upper-case letters represent 
specifications that are to appear in 
the actual statement exactly as shown 
in the statement format. For example, 
JOB in the operation field of the JOB 
statement should be punched exactly as 
shown. 



2. All lower-case letters represent 

generic terms that are to be replaced 
in the actual statement. For example, 
jobname is a generic term that should 
be replaced by the name that the 
programmer is giving his job. 



3. Hyphens are used to join two or more 
words in order to form a single 
generic term. For example, 
device-address is one generic tern. 



Brackets are used to indicate that a 
specification is optional and is not 
always required in the statement. For 
example, [type] indicates that the 
programmer's replacement for the 
generic term, type, may or may not 
appear in the statement, depending on 
the programmer's requirements. 



5. Braces enclosing stacked items 

ind icate that a choice of one item 
must be made by the programmer. For 
example: 



Comments in Job Control Statements 



SYS 
PFOG 
ALL 
SYSxxx 



Comment statements (i.e., statements 
preceded by an asterisk in column 1 
followed by a blank) may be placed anywhere 



indicates that either SYS, PROG, ALL, 
or SYSxxx must appear in the actual 
statement. 



i 
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Brackets enclosing stacked items 
indicate that a choice of one item 
may, but need not, be made by the 
programmer. For example: 

,X'ss* 

,ALT 

indicates that either ,X'ss' or .ALT 
but not both, may appear in the actual 
statement, or the specification can be 
omitted entirely. 



/. iixx pum-;«-ucn-x«->n mcarKS snown in t:.ne 
statement formats other than hyphens, 
brackets, and braces must be punched 
as shown. This includes periods, 
commas, and parentheses. For example, 
, [date] means that the specification, 
if present in the statement, should 
consist of the programmer's 
replacement for the generic term date 
preceded by the comma with no 
intervening space. Even if the date 
is omitted, the comma must be punched 
as shown. 



The label statements must be in the 
order: 

DLBL 

EXTENT (one for each area or file in 
the volume) 



or 



TLBL 

and must immediately precede the EXEC 
statement to which they apply. 



DESCRIPTION AND FORMATS OF JOB CONTROL 
STATEMENTS 



This section contains descriptions and 
formats of job control statements. 



The ellipsis (...) indicates where 
repetition may occur at the 
programmer's option. The portion of 
the format that may be repeated is 
determined as follows: 

a. Scanning right to left, determine 
the bracket or brace delimiter 
immediately to the left of the 
ellipsis. 

b. Continue scanning right to left 
and determine the logically 
matching bracket or brace 
delimiter. 

c. The ellipsis applies to the words 
and punctuation between the pair 
of delimiters. 



Job control statements, with the 
exception of /*, /S, and ^f contain two 
slashes in columns 1 and 2 to identify 
them. 



JOB Statement 



The JOB control statement indicates the 
beginning of control information for a job. 
The JOB control statement is in the 
following format: 



j // JOB jobname 

L 




Sequence of Job Control Statements 



The job deck for a specific job always 
begins with a JOB statement and ends with a 
/5 (end-of-job) statement. A specific job 
consists of one or m.ore job steps. The 
beginning of a job step is indicated by the 
appearance of an EXEC statement. When an 
EXEC statement is encountered, it initiates 
the execution of the job step, which 
includes all preceding control statements 
up to, but not including, a previous EXEC 
statement. 

The only limitation on the sequence of 
statements within a job step is that which 
is discussed here for the label information 
statements. 



jobname 

is a programmer-defined name 
consisting of from one to eight 
alphanumeric characters. Any user 
comments can appear on the JOB control 
statement following the jobname 
(through column 72). The time of day 
and date appear in columns 73 to 80 
when the JOB statement is printed on 
SYSLST. The time of day and date are 
also printed in columns 1 through 8 on 
the next line of SYSLOG. 

If a job is restarted, the jobname 
must be identical to that used when 
the checkpoint was taken. 

Note : The JOB statement resets the effect 
of all previously issued OPTION and ASSGN 
control statements . 
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ASSGM Stc 



:em( 



coniirianu, because ASSGN also opens the 
file. 



The ASSGN control statement assigns a 
logical input/output unit to a physical 
device. An ASSGN control statement must be 
present in the job deck for each data file 
assigned to an external storage device in 
the COBOL program where these assignments 
differ from those established at system 
generation time. Data files are assigned 
to programmer logical units in COBOL by 
means of the source language ASSIGN clause. 
An ASSGN statement or command can also be 
used 

• to unassign a logical unit to free it 
for assignment to another partition 

• to ignore the assignment of a logical 
unit, that is, program references to 
the logical unit are ignored (useful in 
testing and certain rerun situations) 

• to specify an alternate tape unit to be 
used when the capacity of the original 
is reached. 

The assignment routines check the 
operands of the ASSGN statement/command for 
the relationship between the physical 
device, the logical unit, the type of 
assignment (peritianent or temporary), etc. 
The following list summarizes the most 
pertinent items to remember when making 
assignments: 

1. Assignments are effective only for the 
partition in which they are issued. 

2. No physical device except DASD can be 
assigned to more than one active 
partition at the same time. 

3. All system input and output file 
assignments to disk or diskette must 
be permanent. 

4. SYSIN must be assigned if both SYSRDR 
and SYSIPT are to be assigned to the 
same extent. 

5. SYSOUT cannot be assigned to disk or 
diskette; it must be a permanent 
assignment if assigned to tape. 

6„ SYSLNK must be assigned before issuing 
the LINK or CATAL option in the OPTION 
statement; otherwise, the option is 
ignored and the message 'PLEASE ASSIGN 
SYSLNK' is issued to the operator. 

7. If SYSRDR, SYSIPT, SYSLST, or SYSPCH 
is assigned to tape or diskette, or 
disk when the system is generated, it 
will be unassigned by IPL. Such 
assignments can be made effective only 
with the job control ASSGN statement or 



8. Before a tape unit is assigned to 
SYSLST, SYSPCH, or SYSOUT, all 
previous assignments to this tape unit 
must be permanently unassigned. This 
may be done by using a DVCDN command 
instead. 

9. The assignm.ent of SYSLOG cannot be 
changed while a foreground partition 
is active. 

10. SYSRES, SYSCAT, and SYSVIS can never 
be assigned by an ASSGN statement or 
command. An IPL is required to change 
these assignments. 

The ASSGN control statement may also be 
used to change a system standard assignment 
for the duration of the job. 

The format of the ASSGN control 
statement is as follows: 




SYSxxx 

is one of the logical devices listed 
in Table 2. 

Exception : SYSOUT must be assigned 
using the ASSGN job control command. 
Job control commands are described in 
detail in the publication DOS/VS 
System Control Statements . 



device-address 

allows four different formats: 

cuu (Rel. 35 and up) 
or 

X'cuu' 

where c is the channel number and uu 
the unit number in hexadecimal 
notation. The values of 'cuu' are 
determined by each installation. 

c = for multiplexor channel, 
1 through 6 for selector 
channels 1 through 6. 

uu = 00 to FE (0 to 254) in 
hexadecimal. 



indicates that the logical unit 
to be unassigned. Any source 
language input/output operation 
attempted on this device causes 
cancellation of the job. 



IS 



2U 



IGN 



indicates that the logical unit is 
to be unassigned. Each time a READ 
statement for the file assigned to 
IGN is encountered, control will be 
transferred to the 
imperative-statement following the 
AT END option. The IGN option is 
not valid for SYSRDR, SYSIPT, and 
SYSIN. This option is useful in 
program debugging since source 
language references to input files 
residing on symbolic units for which 
IGN has been specified are ignored. 
Any file for which the IGN option is 
used must be a sequential input 
file. Output files assigned with 
the IGN option are not supported by 
DOS/VS COBOL object programs. 



The COBOL programmer may assign only the 
programmer logical units (SYSOOO through 
SYS2'+0, depending on the number of 
partitions) to data files used in his 
program. For example, if the following 
ASSIGN clause is used, 

SELECT IN-FILE ASSIGN TO SYS00 4-DA-2314-S 

an ASSGN control statement must appear in 
the job deck which assigns SYS004 to a 
physical device if the physical device 
differs from the permanent assignment. In 
this case, the physical device must be a 
2314 direct access device. An example of 
such a control statement is: 

// ASSGN SYS004,X'00C' 



X'ss' 



ALT 



is the device specification. It is 
used for specifying mode settings for 
7-track and dual density 9-track 
tapes. If X'ss' is not specified, the 
system assumes the value specified at 
system generation for 7-track tapes 
and X'CO' for 9-track tapes. The 
possible specifications for X'ss* are 
shown in Figure 3 . 



must be specified in the control 
statement that assigns an alternate 
magnetic tape unit which is used when 
the capacity of the original 
assignment is reached. The 
specifications for the alternate unit 
must be the same as those of the 
original unit, since X'ss* cannot be 
specified. The characteristics of the 
alternate unit must be the same as 
those of the original unit. Multiple 
alternates can be assigned to a 
symbolic unit. 



indicates input hopper one for 2560 or 
5425. 



indicates input hopper two for 2560 or 
542 5. H2 may only be assigned to 
SYSRDR, SYSIPT or SYSPCH. 



Device assignments made by the ASSGN 
control statement are considered temporary. 
They are in effect until another ASSGN 
control statement or a RESET statement for 
that logical unit, or the next /% or JOB 
statement is read, whichever occurs first. 
If a RESET, /S, or JOB statement is 
encountered, the assignment reverts to the 
standard assignment established at system 
generation time plus any modification by an 
ASSGN command. 



HI 



H2 



Physical unit X'OOC was permanently 
assigned to a 2314 direct access device at 
system generation time. 



Note; The ASSGN control statement is 
necessary only when the symbolic unit 
assignment is being made to a physical 
device address which differs from that 
established at system generation time. 

"Appendix H: Sample Job Decks" contains 
illustrations of ASSGN statement usage. 
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9-Track Tape 



single density 9-track 
single density 9-track 
dual density 9-track 
dual density 9-track 
single density 9-track 
dual density 9-track 
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Figure 



3. Possible Specifications for 
X'ss* in the ASSGN Control 
Statement 
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CLOSE Statement 



The CLOSE control statement is used to 
close either a system or programmer logical 
unit assigned to tape. As a result of the 
CLOSE control statement, a standard 
end-of-volume label set is written and the 
tape is rewound and unloaded. The CLOSE 
statement applies only to a temporarily 
assigned logical unit, that is, a logical 
unit for which an ASSGN control statement 
has been specified within the same job. 
The format of the CLOSE control statement 
is as follows: 



IGN 



ALT 



specifies that the logical unit is to 
be closed and unassigned with the 
ignore option. This operand is 
invalid for SYSRDR, SYSIPT, or SYSIN. 



specifies that the logical unit is to 
be closed and an alternate unit is to 
be opened and used. This operand is 
valid only for system logical output 
units (SYSPCH, SYSLST, or SYSOUT) 
currently assigned to a iragnetic tape 
unit. 



// CLOSE SYSxxx 



',X'cuu" [,X'SS*] 

,UA 

,IGN 

,ALT 



The logical unit can optionally be 
reassigned to another device, unassigned, 
or switched to an alternate unit. 

Note that when SYSxxx is a system 
logical unit, one of the optional 
parameters must be specified. When closing 
a programmer logical unit, no optional 
parameter need be specified. 

SYSxxx 

may only be used for magnetic tape and 
may be specified as SYSPCH, SYSLST, 
SYSOUT, or SYSOOO through SYS240, 
depending on the number of partitions, 

cuu (Rel. 35 and up) 

or 

X'cuu" 

specifies that after the logical unit 
is closed, it will be assigned to the 
channel and unit specified- (See 
"ASSGN Control Statement" for an 
explanation of 'cuu'.) When 
reassigning a system logical unit, the 
new unit will be opened if it is 
either a mass storage device or a 
magnetic tape at load point. 



X'ss' 



UA 



represents device specification for 
mode settings on 7-track and 9-track 
tape. (See "ASSGN Control Statement" 
for an explanation of 'ss'.) If X'ss' 
is not specified, the mode settings 
remain unchanged = 



specifies that the logical unit is to 
be closed and unassigned. 



DATE Statement 



The DATE control statement contains a 
date that is put in the Corrmunication 
Region of the Supervisor. A complete 
description of the fields of the 
Communication Region is given in "Appendix 
G: communication Region." The DATE 
statement is in one of the following 
formats : 

r 1 

|// DATE mm/dd/yy | 

|. _ ^ 

]// DATE dd/mm/yy i 

L J 

I 
where: 

mm = month (01 to 12) 

dd = day (01 to 31) 

yy = year (00 to 99) 

The format to be used is the format 
selected when the system was generated. 

When the DATE statement is used, it 
applies only to the current job being 
executed. The Job Control Processor does 
not check the operand except to ensure that 
its length is eight characters. If no DATE 
statement is specified in the current job, 
the Job Control Processor supplies the date 
given in the last SET command. The SET 
command is discussed in detail in the 
publication DOS/VS System Control 
Statements . 

A DATE statement should be included in 
every job deck that has as one of its job 
steps the execution of a COBOL program that 
utilizes the special register CURRENT-DATE, 
if the date desired is other than that 
designated in the previous SET command. 

The DATE statement should be used at 
com.pile time so that the DATE-COMPILED 
paragraph is accurate and the WHEN-COMPILED 
special register is effective. i 
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TLBL Statement 



The TLBL control statement replaces the 
VOL and TPLAB combination used in previous 
versions of the system. However, the 
current system will continue to support 
these statements. The TLBL control 
statement contains file label information 
for tape label checking and writing. Its 
format follows: 



I// TLBL filename, 

I [, 'file-identifier '][ /date] 

I [ ,f ile-serial-nuinber] 

I [ jvolume-sequence-nuinber] 

I [ ,f ile-sequence-number] 

I [, generation-number] 

I [ ,version-niainber] 



filename 

identifies the file to the control 
program. It can be from three to 
seven characters in length. If the 
following SELECT sentence appears in a 
COBOL program; 

SELECT NEWFILE ASSIGN TO 
SyS003-OT-2400-S-ODTFILE 

the filename operand on control 
statements for this file must be 
OUTFILE. If the SELECT clause were 
coded : 

SELECT NEWFILE ASSIGN TO 
SYS003-DT-2400-S 

the filename operand on the control 
statement for the file must be SYS003. 

•file-identifier* 

consists of from 1 to 17 characters, 
contained within apostrophes, 
indicating the name associated with 
the file on the volume. This operand 
may contain embedded blanks. If this 
operand is omitted on output files, 
the filename will be used. If this 
operand is omitted on input files, no 
checking will be done. 



date 



consists of from one to six 
characters, in the format yy/ddd, 
indicating the expiration date of the 
file for output or the creation date 
for input. (The day of the year may 
consist of from one to three 
characters.) For output files, a one 
to four character retention period 
(d-dddd) may be specified. If this 
operand is omitted, a 0-day retention 
period will be assumed for output 
files. For input files, no checking 
will be done if this operand is 



omitted or if a retention period is 
specified. 



file-serial -number 

consists of from one to six characters 
indicating the volume serial number of 
the first (or only) reel of the file. 
If fewer than six characters are 
specified, the field will be 
right-justified and padded with zeros. 
If this operand is omitted on output 
files, the volume serial number of the 
first (or only) reel of the file will 
be used. If the operand is omitted on 
input files, no checking will be done. 



volume-sequence -number 

consists of from one to four 
characters in ascending order for each 
volume of a multivolume file. This 
number is incremented automatically by 
OPEN and CLOSE routines as required. 
If this operand is omitted on output 
files, BCD 0001 will be used. If 
omitted on input files, no checking is 
done. 



file-sequence-number 

consists of from one to four 
characters in ascending order for each 
file of a multifile volume. This 
number is incremented automatically by 
OPEN and CLOSE routines as required. 
If this operand is omitted on output 
files, BCD 0001 will be used. If it 
is omitted on input files, no checking 
will be done. 



generation-number 

consists of from one to four numeric 
characters that modify the 
file-identifier. If this operand is 
omitted on output files, BCD 0001 is 
used. If it is omitted on input 
files, no checking will be done. 



version-number 

consists of from one to two numeric 
characters that modify the generation 
number. If this operand is omitted on 
output files, BCD 01 will be used. If 
it is omitted on input files, no 
checking will be done. 



Note: If a tape file with standard labels 
is opened two different ways in the same 
COBOL program, and that file resides on a 
multifile volume, the programmer should use 
two separate TLBL cards with different 
filenames specified on each. 
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DLBL Statement 



The DLBL control statement, in 
conjunction with the EXTENT statement, 
replaces the VOL, DLAB, and XTENT 
combination used in previous versions of 
the Disk Operating System. The DLBL 
statement has the following format: 

I 1 

I// DLBL filename I 

I ,[ »file-identifer» ],[ date], [codes] I 

I , [BLKSIZE=n], (CISIZE=n) ' 

filename 

identifies the file to the control 
program. It can be from three to 
seven characters long. If the 
following SELECT sentence appears in a 
COBOL program: 

SELECT INFILE ASSIGN TO 
SYS005-DA-2314-A-INPUTA 

the filename operand on control 
statements for this file must be 
INPUTA. If the SELECT sentence is 
coded: 

SELECT INFILE ASSIGN TO 
SYS005-DA-2314-A 

the filename operand on control 
statements for the file must be 
SYSOOS. 

•file-identifier* 

is the name associated with the file 
on the volume. This can consist of 
from 1 to 44 alphanumeric characters 
contained within apostrophes, 
including the file-identifier and, if 
used, generation-number and version- 
number of generation . If fewer than 
44 characters are used, the field is 
left- justified and padded with blanks. 
If this operand is omitted, filename 
will be used. 



for a file opened aj 
is ignored. 



IHPOT or I 



date 



consists of from one to six characters 
indicating either the retention period 
of the file in the format d through 
dddd (0-9999) , or the absolute 
expiration date of the file in the 
format yy/ddd. When the d through 
dddd format is used, the file is 
retained for the number of days 
specified as dddd. For example, if 
date is specified as 31, the file will 
be retained a month from the day of 
creation. When the yy/ddd format is 
used, the file is retained until the 
day (ddd) in the year (yy) specified. 
For example, if date is specified as 
90/200, the file will be retained 
through the 200th day of the year 1990. 

If date is omitted when the file is 
created, a 7-day retention period is 

assumed. If this operand is present 



codes 

is a 2 to 4 character field indicating 
the type of file label, as follows: 

SD = Sequential Disk 
DA = Direct Access 
ISC = Indexed Sequential using Load 

Create 
ISE = Indexed Sequential using Load 
Extension, Add, or Retrieve 
DU = 3540 Diskette 
VSAM = VSAM file 

If code is omitted, SD is assumed. 

BLKSIZE=n 

specifies the number of bytes in a 
physical record. n must be less 
than 32,768. This parameter is 
valid for the 3330-11 and 3350 devices 
only, and its use is limited to 
sequential files. If specified, it 
overrides the BLKSIZE specification 
in the definition of the file (DTP) . 
It permits reblocking of existing 
files to a new physical record size 
when they are transferred to a 
3330-11 or 3350 device, without 
requiring recompilation of the DTP. 
If the BLKSIZE parameter is not 
specified in the DLBL statement, the 
new files are assumed to have the 
blocksize specified in the DTP. This 

I parameter is not valid for the compiler^ 

I workfiles. 

For further information, see DOS/VS 
System Control Statements . 

CISIZE=n 

specifies the control interval size 
for SAM files on fixed block devices, 
and improves space allocation on such 
devices. The size specified must 
be a multiple of the value specified 
in the BLKSIZE=n operand. This 
operand is valid only for a DLBL 
statement with the code SD. It is 
not valid for compiler workfiles. 

"Appendix H: Sample Job Decks" contains 
illustrations of DLBL statement usage. 

See the section "Processing 3540 
Diskette Unit Files" for the use of DLBL 
Cards for 3540 and the section "Virtual 
Storage Access Method" for use of DLBL 
cards for VSAM. 

EXTENT Statement 

The EXTENT control statement defines 
each area (or extent) of a DASD file — a 
file assigned to a mass storage device. 
One or more EXTENT control statements must 
follow each DLBL statement. 



The EXTENT control statement replaces 
the XTENT statement used in previous 
versions of the Disk Operating System. For 



i 
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more information on the XTEBT statement, 
see DOS/VS System Control Statements . 

The format of the EXTENT control 
statement is: 



I// EXTENT [ symbolic-unit ],[ serial-number]! 

I ,[ type ],[ sequence-number ] | 

I ,[ relative-track ],[ number-of -tracks] | 

I ,[ split-cylinder-track ],[ B=bins ] | 



~«-. V^T 



sym 



is a 6-character field indicating the 
symbolic unit (SYSxxx) of the volume 
for which this extent is effective. 
If this operand is omitted, the 
symbolic unit of the preceding EXTENT 
statement will be used. When 
specified, symbolic-unit may be any 
SYSxxx assigned to the device type 
indicated in the SELECT sentence for 
the file. For example, if the 
following coding appears in a COBOL 
program: 

SELECT OUTFILE ASSIGN TO 
SYS004-DA-2314-A 

the symbolic unit in the EXTENT 
control statement can by any SYSxxx 
assigned to a 2314 disk pack. The 
symbolic unit operand is not required 
for an IJSYSxx filename, where xx is 
IN, PH, LS, RS, SL, or RL. If SYSRDR 
or SYSIPT is assigned, this operand 
must be included. 

serial-number 

consists of from one to six characters 
indicating the volume serial number of 
the volume for which this extent is 
effective. If fewer than six 
characters are used, the field will be 
right- justified and padded with zeros. 
If this operand is omitted, the volume 
serial number of the preceding EXTENT 
control statement will be used. If no 
serial number was provided in the 
EXTENT control statement, the serial 
number will not be checked and it will 
be the programmer's responsibility if 
files are destroyed as a result of 
mounting the incorrect volume. 



type 



consists of one character indicating 
the type of the extent, as follows: 

1 -- Data area (no split cylinder) 

2 -- Overflow area (for an indexed 

file) 
4 — Index area (for an indexed file) 
8 — Data area (split cylinder) 

If this operand is omitted, 1 is 
assumed. 



sequence-number 

consists of from one to three 
characters containing a decimal number 
from to 255 indicating the sequence 
number of this extent within a 
multi-extent file. Extent sequence 
is used for the master index of an 
indexed file. If the master index is 
not used, the first extent of an 
indexed file has the sequence number 
1. The extent sequence number for all 
other types of files begins with 0. 
If this operand is omitted for the 
first extent of ISAM files, the extent 
will not be accepted. For SD or DA 
files, this operand is not required. 
For DA files this operand should be 
specified when using more than one 
EXTENT for a file. Direct files can 
have up to five extents. Indexed 
files can have up to eleven data 
extents (nine prime, one cylinder 
index, one separate overflow). 

relative- track 

consists of from one to five 
characters indicating the sequential 
number of the track, relative to zero, 
where the data extent is to begin. If 
this field is omitted on an ISAM file, 
the extent will not be accepted. This 
field is not required for DA input or 
for SD input files (the extents from 
the file labels will be used). 

For fixed block devices, this operand 
is a niomber from 2 to 2,147,483,645 
that specifies the physical block 
at which the extent should start. 

Formulas for converting actual to 
relative track addresses (RT) and 
relative track to actual for the DASD 
devices follow. 



Actual to Relative : 

2311 10 X cylinder number + track 
number = RT 

2314 20 X cylinder number + track 

or number = RT 
2319 



2321 1000 X subcell number + 100 x 
strip number + 20 x block 
number + track number = RT 

3330 19 X cylinder number + track 
number = RT 

3340 12 X cylinder number + track 
number = RT 



3350 30 X cylinder number + track 
number = RT 



■ 



Preparing COBOL Programs for Processing 29 



Relative to Actual; 



2311 



2314 

or 
2319 



RT = quotient is cylinder 
10 remainder is track 

RT = quotient is cylinder, 
20 remainder is track 



3330 RT = quotient is cylinder, 

19 remainder is track 

2321 RT = quotient is subcell, 
1000 remainderl 

remainderl = quotient is strip, 
100 remainder2 

reir.ainder2 = quotient is block, 

20 remainder is track 

3340 RT = quotient is cylinder, 
12 remainder is track 



3350 RT = quotient is cylinder, 
30 remainder is track 

number-of -tracks 

consists of from one to five 
characters indicating the number of 
tracks to be allocated to the file. 
For SD input files, this field may be 
omitted. The nxomber of tracks for a 
split cylinder file must be a multiple 
of the number of cylinders specified 
for the file and the number of tracks 
specified for each cylinder. 

For fixed block devices, this operand 
is a number from 1 to 2,147,483,645 
that specifies the nximber of physical 
blocks in the extent. 

split-cylinder-track 

consists of from one to two 
characters, with a value of through 
19, indicating the upper track number 
for the split cylinder in SD files. 



bins 



consists of from one to two characters 
identifying the 2321 bin that the 
extent was created for, or on which 
the extent is currently located. If 
the field is one character, the 
creating bin is assumed to be zero« 



There is no need to specify a creating 
bin for SD or ISAM files. If this 
operand is omitted, bin is assumed 
for both bins. If the operand is 
included and positional operands are 
omitted, only one comma is required 
preceding the keyword operand. If any 
operands preceding the bin 
specification are omitted, one comma 
for each operand is acceptable, but 
unnecessary. 

Figure 4 shows examples of using the 
DLBL statement in conjunction with the 
EXTENT statement. "Appendix H: Sample Job 
Decks" contains illustrations of EXTENT 
statement usage. 

VOL, DLAB, TPLAB AND XTENT STATEMENTS 

These statements have been replaced by 
the DLBL, TLBL, and EXTENT statements, and, 
although they are still supported by the 
Disk Operating System, they cannot be used 
for 3330 or 3340 disk files, or for VSAM 
files. Details as to their usage can be 
found in DOS/VS System Control Statements . 
For their use with respect to COBOL, see 
IBM DOS Full American National Standard 
COBOL Programmer* s Guide . When new label 
information statements are prepared, DLBL, 
TLBL, and EXTENT should be used. 

LBLTYP Statement 

The LBLTYP control statement defines the 
amount of storage to be reserved at linkage 
edit time in the problem program area of 
storage in order to process tape and 
nonsequential DASD file labels. It applies 
to both background and foreground object 
programs, and is required if the file 
contains standard labels. 

The LBLTYP control statement immediately 
precedes the // EXEC LNKEDT statement in 
the job deck, with the exception of 
self-relocating programs for which it is 
instead submitted immediately preceding the 
// EXEC statement for the program. The 
format of the LBLTYP control statement is: 



i 

j// LBLTYP 

I 

L 



TAPE({nn)] 
NSD(nn) 



Direct file: 



The following DLBL and EXTENT statements describe a direct file occupying 840 
tracks, beginning on relative track 10. 

// DLBL MASTER, ,75/001, DA 

// EXTENT SYS015,111111,1,0,10,840 
Indexed file: 



The following DLBL and EXTENT statements describe an indexed file on a 2314 
occupying 100 tracks, beginning on relative track 1100. The first EXTENT allocates a 
20-track cylinder index. The second EXTENT allocates a 80-track data area. 

// DLBL MASTER,, 75/001, ISC 

// EXTENT SYS015, mill, 4,1, 1100, 20 

// EXTENT SYS015, mill, 1,2, 1120, 80 

L 

Figure 4. Sample Label and File Extent Information for Mass Storage Files 
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TAPE[(nn)] 

is used only if tape files requiring 
label information are to be processed 
and if no nonsequential DASD files are 
to be processed. nn is optional and 
is present only for future expansion. 
It is ignored by the Job Control 
Processor. 

NSD(nn) 

is used if any nonsequential DASD 
files are to be processed, regardless 
of other type files that are used, nn 
specifies the largest number of 
extents to be used for a single file. 

LISTIO Statement 



The LISTIO control statement causes the 
system to print a list of input/om.tput 
assignments on SYSLST. The format of the 
LISTIO control statement is: 

SYS 
PROG 
BG 
Fl 
F2 
F3 
F4 
// LISTIO ( ALL 

SYSxxx 
UNITS 
DOWN 
UA 

cuu 

X'cuu' 

ASSGN (Rel. 35 and up) 



ALL 



causes the physical units assigned to 
all logical units to be listed. 



SYSxxx 

causes the physical units assigned to 
the logical unit specified to be 
listed. 



UNITS 



DOWN 



UA 



causes the logical units assigned to 
all physical units to be listed. 



causes all physical units specified as 
inoperative to be listed. 



causes all physical units not 
currently assigned to a logical unit 
to be listed. 



cuu (Release 35 and up) 
or 

X'cuu* 

causes the logical units assigned to 
the physical unit specified to be 
listed. 



ASSGN 



causes all system and program logical 
units assigned to the current partition 
to be listed. 




SYS 



PROG 



BG 



Fl 



F2 



F3 



FU 



causes the physical units assigned to 
all system logical units to be listed. 



causes the physical units assigned to 
all background programmer logical 
units to be listed. 



lists the physical units assigned to 
all logical units of the background 
partition. 



causes the physical units assigned to 
all foreground-one logical units to be 
listed. 



causes the physical units assigned to 
all foreground-two logical units to be 
listed. 



causes the physical units assigned to 
all foreground-three logical units to 
be listed. 

causes the physical units assigned to 
all foreground-four logical units to 
be listed- 



MTC Statement 



The MTC control statement controls 24 00 
and 3400 series magnetic tape operations. 
The format is as follows: 



// MTC opcode, fSYSxxxi[,nn] 
< X ' cuu ' > 



(cuu ) J 



opcode 

specifies the operation to be 
performed, opcode can be chosen from 
the following: 

BSF — Backspace to tapemark 

BSR — Backspace to interrecord gap 

ERG — Erase gap (write blank tape) 

FSF — Forward space to tapemark 

FSR — Forward space to interrecord 

gap 

RUN — Rewind and unload 
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REW — Rewind 

WTM — Write tapemark 

SYSxxx 

represents any logical unit assigned 
to magnetic tape upon which the MTC 
control statement is to operate. 

X • cuu ' 

represents any physical unit assigned 
to magnetic tape upon which the MTC 
control statement is to operate. 

[,nn3 

is the decimal number (01 through 99) 
which, if specified, represents the 
number of times the operation is to be 
performed- If nn is omitted, the 
operation is performed once. 

OPTION Statement 



The OPTION control statement is used to 
specify one or more of the options of the 
Job Control Processor. The format of the 
OPTION statement is : 



NODUMP 

suppresses the DUMP option, 

LINK 

indicates that the object module is to 
be link edited. When the LINK option 
is used, the output of the COBOL 
compiler is written on SYSLNK. The 
LINK option must always precede an 
EXEC LNKEDT statement in the job deck. 
(CATAL also causes the LINK option to 
be set.) LINK is not acceptable to 
the Job Control Processor operating in 
the foreground unless the private core 
image library option is supported and 
a private core image library is 
assigned. 

NOLINK 

suppresses the LINK option. The COBOL 
compiler can also suppress the LINK 
option if the program contains an 
error that would preclude the 
successful execution of the program, 
or if SYNTAX is in effect, or if 
CSYNTAX is in effect and an E-level 
error is encountered. 



|// OPTION optionl[,option2] i 

L . 

The order in which the selected options 
appear in the operand field is arbitrary. 
Options are reset to the standard 
established at system generation time upon 
encountering the next JOB statement or the 
/g statement. 



The options are: 



LOG 



causes the listing of columns 1 
through 80 of all control statements 
on SYSLST. If LOG is not the standard 
established at system generation time, 
control statements are not listed 
until a LOG option is encountered. 
Once a LOG option statement is read, 
logging continues from job step to job 
step until a NOLOG option is 
encountered or until either the JOB or 
/g control statement is encountered. 



NOLOG 



suppresses the listing of all control 
statements on SYSLST until a LOG 
option is encountered, or until either 
the JOB or /6 control statement is 
encountered. 



DECK 

causes the COBOL compiler to punch an 
object module on SYSPCH. If both DECK 
and LINK are specified, the output of 
the compiler is written on both SYSPCH 
and SYSLNK.^ 

NODECK 

suppresses the DECK option. The DECK 
option is also suppressed if SYNTAX is 
in effect, or if CSYNTAX is in effect 
and E-level errors exist. 

LIST 

causes the compiler to write the COBOL 
source statements on SYSLST. If 
lister is in effect, the LIST option 
is overridden; LISTER causes a listing 
regardless of whether LIST or NOLIST 
is specified, 

NOLIST 

suppresses the LIST option. 



LISTX 



causes the COBOL compiler to write a 
Procedure Division map on SYSLST. In 
addition, global tables, literal 
pools, register assignments, and 
procedure block assignments will be 
provided. You may want to use the CBL 



DUMP 



causes a dump of the registers and 
virtual storage to be printed on 
SYSLST in the case of an abnormal 
program termination (such as a program 
check). Using the compiler SYMDMP, 
FLOW, or STATE features, it may not be 
necessary to use this option. 



■"The //option card options pertaining to 
the compiler will be suppressed if the 
"LISTER ONLY" option of lister is in 
effect. Otherwise, when "LISTER AND 
COMPILE" is in effect, the options 
specified will be in effect for 
compilation. 



< 
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option CLIST (condensed list) in place 
of this.^ ' 

NOLISTX 

suppresses the LISTX option, as do the 
same conditions as cause DECK to be 
suppressed- 



XREF 



causes the COBOL compiler to write a 
symbolic cross-reference list on 
SYSLST. You may want to use the CBL 
option SXREF in place of this, or the 



3 +^ i .~.n ^.'^- 



lister cross-reference information 
large COBOL programs. 

NOXREF 

suppresses the XREF option. SXREF 
also suppresses XREF, as do the same 
conditions as cause DECK to be 
suppressed. 



SYM 



causes the COBOL compiler to write a 
Data Division map on SYSLST. In 
addition, global tables, literal 
pools, register assignments, and 
procedure block assignments will be 
provided.^ 



NOSYM 



suppresses the SYM option. 



ERRS 



causes the COBOL compiler to write the 
diagnostic messages related to the 
source program on SYSLST-^ 

NOERRS 

suppresses the ERRS option. It does 
not suppress FIPS messages. 

CATAL 

causes the cataloging of a phase or 
program in the core image library upon 
completion of a linkage editor job 
step. CATAL also causes the LINK 
option to be set. CATAL is not 
accepted by the Job Control Processor 
operating in a batched- job foreground 
environment unless the private core 
image library option is supported and 
a private core image library is 
assigned. 

STDLABEL 

causes the standard label track to be 
cleared and all DASD or tape labels 
submitted after this point to be 



^The //option card options pertaining to 
the compiler will be suppressed if the 
"LISTER ONLY" option of lister is in 
effect. Otherwise, when "LISTER AND 
COMPILE" is in effect, the options 
specified will be in effect for 
compilation - 



written on the standard label track. 
This option is reset to the USRLABEL 
option at end-of-job or end-of-job 
step. All file definition statements 
submitted after the STDLABEL option 
are available to any program in any 
area until another set of standard 
file definition statements is 
submitted. STDLABEL is not accepted 
by the Job Control Processor operating 
in a batched- job foreground 
environment. All file definition 
statements following OPTION STDLABEL 
are included in the standard file 
definition set until one of the 
following occurs: 



• End-of-job step 

• End-of-job 

• OPTION USRLABEL is specified 

• OPTION PARSTD is specified 

USRLABEL 

causes all DASD or tape labels 
submitted after this point to be 
written at the beginning of the user 
label track. 

PARSTD 

causes all DASD or tape labels 
submitted after this point to be 
written at the beginning of the 
partition standard label track. The 
PARSTD option is reset to the USRLABEL 
option at end-of-job or end-of-job 
step. All file definition statements 
submitted after the PARSTD option will 
be available to any program in the 
current partition until another set of 
partition standard file definition 
statements is submitted. All file 
definition statements submitted after 
OPTION PARSTD will be included in the 
standard file definition set until one 
of the following occurs: 

• End-of-job step 

• End-of-job 

• OPTION USRLABEL is specified 

• OPTION STDLABEL is specified 

For a given filename, the sequence of 
search for label information during an 
OPEN is the USRLABEL area, followed by 
the PARSTD area, followed by the 
STDLABEL area. 

Note: If NOLINK and NODECK are requested 
on the OPTION control statement and either 
SYMDMP or OPT is specified on the CBL card, 
the SYMDMP or OPT specification is ignored. 
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The options specified in the OPTION 
statement remain in effect until a 
contradictory option is encountered or 
until a JOB control statement is read. In 
the latter case, the options are reset to 
the standard that was established at system 
Qeneration time. 



j// RESET 



( SYS 
3 PROG 
\ ALL 
I SYSxxx 



Any assignment for SYSLNJK, after the 
occurrence of the OPTION statement, cancels 
the LINK and CATAL options. These two 
options are also canceled after each 
occurrence of an EXEC statement with a 
blank operand. 



SYS 



PROG 



resets all system logical units to 
their standard assignments. 



resets all programmer logical units to 
their standard assignments. 



PAUSE Statement 



The PAUSE control statement allows for 
operator intervention between job steps. 
The format of the PAUSE control statement 
is: 



|// PAUSE [comments] 

L 



ALL 

resets all system and programmer 
logical units to their standard 
assignments. 

SYSxxx 

resets the logical unit specified to 
its standard assignment. 



The PAUSE control statement is effective 
just before the next input control 
statement in the job deck is read. The 
PAUSE control statement always prints on 
SYSLOG and SYSLST. 

An example of this statement is: 

// PAUSE SAVE SYS004, SYS005, MOUNT 
NEW TAPES 

This sample statement instructs the 
operator to save the output tapes and mount 
two new tapes. 

When the PAUSE statement is encountered 
by the Job Control Processor, processing is 
stopped in the partition until a response 
is given. The end/enter key causes 
processing to continue. 



RESET Statement 



RSTRT Statement 



A restart facility is available for 
checkpoint programs. A programmer can use 
the source language RERUN clause in his 
program to cause checkpoint records to be 
written. This allows sufficient 
information to be stored so that program 
execution can be restarted at a specified 
point. The checkpoint information includes 
the registers, tape positioning 
information, a dump of virtual storage, and 
a restart address. 

The restart facility allows the 
programmer to continue execution of an 
interrupted job at a point other than the 
beginning. The procedure is to submit a 
group of job control statements including a 
RSTRT control statement. The format is as 
follows: 



The RESET control statement resets 
input/output assignments to the standard 
assignments. The standard assignments are 
those specified at system generation time 
plus any modifications made by the operator 
by means of the ASSGN command without the 
TEMP option- The RESET command is 
discussed in detail in the publication 
DOS/VS System Control Statements . The 
format of the RESET statement is : 



I// RSTRT SYSxxx,nnnn[ ,filename] 

L 



SYSxxx 

is the symbolic unit name of the 2400, 
3410, 3420, 2311, 2314, 2319, 3330, 
3340, 3350, or fixed block devices 
checkpoint file used for restarting. 
This unit must have been assigned 
previously. 
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nnnn 



is the identification of the 
checkpoint record to be used for 
restarting. This serial number 
consists of four characters- It 
corresponds to the checkpoint 
identification used when the 
checkpoint was taken- The serial 
number is supplied by the checkpoint 
routine. 



filename 

is the symbolic name of the disk 
checkpoint file used for restarting. 
It must be identical to the SYSxxx of 
the system-name specified in the 
RERUN clause. 



The UPSI byte is the 2Uth byte in the 
Communication Region of the Supervisor. A 
complete description of the fields of the 
Communication Region is given in "Appendix 
G: Communication Region™" The Job Control 
Processor clears the UPSI byte to binary 
zeros before reading control statements for 
each job. When the UPSI control statement 
is read, the Job Control Processor sets 
these bits to the programmer's 
specifications. Any combination of the 
eight bits can be tested in the COBOL 
source program at execution time by means 
of the source language switches UPSI-0 
throuah UPS I- 7. 



EXEC Statement 



When a checkpoint is taken, the 
completed checkpoint is noted on SYSLOG- 
Restarting can be done from any checkpoint 
record, not just the last. The jobname 
specified in the JOB statement must be 
identical to the jobname used when the 
checkpoint was taken. The proper 
input/output device assignments must 
precede the RSTRT control statement. 



Assignment of input/output devices to 
symbolic unit names may vary from the 
initial assignment. Assignments are made 
for restarting jobs in the same manner as 
assignments are made for normal jobs. 



See the chapter "Program Checkout" for 
further details on taking checkpoints and 
restarting a program for which checkpoints 
have been taken. 



The EXEC statement (Execute Program or 
Procedure) indicates the end of control 
information for a job step and the 
beginning of execution of a program, in 
which case it must be the last command or 
statement processed before a job step is 
executed. 

// EXEC [[PGM=3programname] [,REAL] [,SIZE] 
[ PROC=pr ocedur ename ] 

PGM=prog ramname 

represents the name of the program in 
the core image library to be executed. 
The program name corresponds to the 
first or only phase of the program in 
the library. The program name can be 
one to eight alphameric characters 
(0-9, A-S, #, $, 3). The first 
character must not be nuirieric. 

If the program to be executed has just 
been processed by the linkage editor, 
the program name is omitted and the 
PGM keyword cannot be used. 



^^^H 

^^^Q 



UPSI Statement 



The UPSI control statement allows the 
programmer to set program switches that can 
be tested by problem programs at execution 
time- The UPSI control statement has the 
following form.at: 



|// UPSI nnnnnnnn 
L 



nnnnnnnn 

consists of from one to eight 
characters of 0, 1, or X. Positions 
containing 1 are set to 1; positions 
containing X are unchanged. 
Unspecified rightmost positions are 
assumed to be X. 



REAL 

indicates that the job step started by 
EXEC will be executed in real mode. 
If REAL is not specified the job step 
is always executed in virtual mode. 
REAL cannot be specified for programs 
using VSAlXl, the 3886, for ISAM 
programs using the ISAM interface 
program or,, for programs compiled with 
the CBL option count. 

SIZE=size 

Size can be nK, AUTO or (AUTO, nK) . 

(a) If specified with REAL, it indicates 
the size of that part of the real 
partition that will be needed by the 
job step's associated EXEC. The 
remaining part of the real partition 
is given to the page pool. 
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If SIZE is omitted and REAL is 
specified, the whole real partition is 
used by the job step. 

In Release 35 (DOS/VS) and up, if the 
COBOL compiler is executed in a real 
partition, a SIZE parameter must be 
specified. Also, make sure there is 
enough real GETVIS space available. 

(b) If used without REAL, it specifies 

that the virtual partition to be used 
by the job step is divided into two 
parts: the lower part with a size of 
nK will contain the program initiated 
with EXEC; the upper part serves as 
additional storage pool for other 
modules (for example, VSAM) required 
by the program in that partition. The 
program reserves the upper storage 
part for its needs by issuing GETVIS 
macros with the required amount of 
storage as parameter; it releases the 
storage by issuing FREEVIS macros. 

If SIZE is omitted, the whole virtual 
partition is used for the job 
initiated with EXEC. 

SIZE (without REAL) must always be 
specified for VSAM programs or for 
ISAM programs using the ISAM Interface 
Program (IIP), as well as for 3886 
processing, and for programs compiled 
with the CBL option count. 

If you specify SIZE=AUTO, the system 
automatically uses the information in 
the core image directory to calculate 
the size of the program to be loaded. 
If you specify SIZE=(AUTO,nK) , The 
system adds nK bytes to the calculated 
length. 

The following restrictions apply to n: 

• n must not be larger than the size 
of the partition it refers to. 

• n must be greater than zero. 

• if n is not a multiple of 2, n+1 is 
used 

Note : If you specify SIZE=AUTO, a 
part of the partition is allocated 
to the page pool. The storage space 
left is not sufficient for the 
compiler program. Thus you should not 
specify SIZE=AUTO in an EXEC FCOBOL 
statement (for more detailed 
infonnation, refer to System Control 
Statements ) . 

Note: If CBL option SYMDMP is used, 
see Appendix F: "System and Size 
Considerations . " 

PROC=procedurename 

represents the name of the procedure 
to be retrieved from the procedure 
library. The procedure name can be 
from one to eight alphanumeric 



characters, the first of which must be 
alphabetic. 

For more information on cataloged 
procedures, as well as the use of 
overwrite statements and the rules 
that apply to temporary procedure 
modification, refer to the DOS/VS 
System Management Guide and the 
chapter "Librarian Functions" in this 
book. 

CBL STATEMENT — COBOL OPTION CONTROL CARD 



Although some options for compilation 
are specified either at system generation 
time or in the OPTION control statement, 
the COBOL compiler provides an additional 
statement, the CBL statement, for the 
specification of compile-time options 
unique to COBOL. 

The CBL card must be placed between the 
EXEC FCOBOL Statement and the first 
statement in the CCBOL program. The CBL 
card cannot be continued. However, if 
specification of options will continue past 
column 71, multiple CBL cards may be used. 

The options shown in the following 
format may appear in any order. No commenti 
should appear in the operand field. 
Underscoring indicates the default case. To 
change the defaults for your installation, 
see "Changing the Installation Defaults." i 



r , SEQ 1 r , FLAGW "1 
CBL [BUF=nnnnn] [ ,NOSEqJ [_ ,FLAGE J 

r,SUPMAP 1 (,SPACEn] r,CLIST 
[ ,NOSUPMAPj L » NOCLI£ 

r ,STXIT 1 r , QUOTE 1 T , TRUNC 1 i" , 
L » NOSTXIT J L , APOST J [ , NOTRUNC J [ , 



] 



ZWB 
NOZWB 



[ 



,SXREF -1 [,PMAP=h] 
, NOSXREF I 



[,FLOW[= 



[=nn]]r. 



STATE 1 
NO STATE I 



, OPTIMIZE 

, NCOPTIMIZE 

,OPT 

, NCCPT 



', SYNTAX 
,CSYNTAX 
, NOSYNTAX 



t , SYMDMP [=f ilename] ] 



[: 



VERBSUM -| 
NOVERBSUM | 



■,VERBREF -ir, COUNT "l 
., NOVERBREF | |, NOCOUNT | 



r,CATALR -]r,LIB "l r,VERB "] 
L ,N0CATALrJ |, N0LIB I I , NOVERB J 




i 
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CBL 

must begin in column 2 (column 1 must 
be blank) and be followed by at least 
one blank. 

BUF=nnnnn 

the BUF option specifies the amount of 
storage to be assigned to each 
compiler work file buffer. nnnnn is a 
decimal number from 512 to 32,767. If 
this option is not specified, 512 is 
assumed. The BUF option should be 
used to specify an optional blocksize 
(which will depend on the device type) 
for the workfiles. Usually, a larger 
blocksize will enhance the performance 
of the compiler. However, for any 
given BUF specification, the compiler 
space requirements (over 64K) are 
increased by a factor of 
6x(nnnnnn-512) . 6x (nnnnnn-51 2K) + 64K 
=partition size. 



SEQ 
NOSEQ 



indicates whether or not the compiler 
is to check the sequence of source 
statements. If SEQ is specified and a 
statement is not in sequence, it is 
flagged. If the lister feature is 
invoked, the source statements are 
resequenced automatically before the 
sequence check is performed. 



FLAGW 
FLAGE 



determines which diagnostics the 
compiler will list. FLAGW indicates 
that all diagnostics will be listed 
(severity levels W, C, E, and D) , 
FLAGE indicates that only those 
diagnostics with severity levels C, E, 
and D will be listed. This has no 
effect on FIPS messages. 

SUPMAP 

NOSUPMAP 

causes the CLIST and LISTX options to 
be suppressed if an E-level diagnostic 
message is produced by the compiler. 
For the DECK option, refer to OBJECT 
MODULE in the chapter "Interpreting 
Output . " 

SPACEn 

indicates the type of spacing to be 
used on the output listing. n can be 
specified as either 1 (single 
spacing), 2 (double spacing), or 3 
(triple spacing) . If the SPACEn 
option is omitted, single spacing is 
provided. Single spacing is always in 
effect if the lister feature is 
invoked. 



CLIST 
NOCLIST 



indicates that a condensed listing is 
to be produced. The condensed listing 
will contain only the address of the 



first generated instruction for each 
verb in the Procedure Division. In 
addition, global tables, literal 
pools, register assignments, and 
procedure block assignments will be 
provided. The CLIST option overrides 
the LISTX or NOLISTX options. The 
LISTX or NOLISTX options are either 
established at system generation time 
or specified in the OPTION control 
statement. 



STXIT 
NOSTXIT 



enables a USE AFTER STANDARD ERROR 
declarative to receive control when an 
input/output error occurs on a unit 
record device. The use of STXIT 
precludes the use of SYMDKP, STATE, 
and FLOW in the compiled program and 
in any other program link-edited with 
the compiled program, and vice versa. 



QUOTE 

APOST 

QUOTE indicates to the compiler that 
the double quotation marks (") should 
be accepted as the character to 
delineate literals; APOST indicates 
that the apostrophe (*) should be 
accepted instead. The compiler will 
generate the specified character for 
the figurative constant QUOTE (S). 

TRUNC 

NOTRUNC 

applies only to CONIPUTATIONAL 
receiving fields in MOVE statements 
and arithmetic expressions- If TRUNC 
is specified, extra code is generated 
to truncate the final intermediate 
result of the arithmetic expression, 
or the sending field in the MOVE 
statement, to the number of digits 
specified in the PICTURE clause of the 
COMPUTATIONAL receiving field. If 
NOTRUNC is specified, the compiler 
assumes that the data being 
manipulated conforms to PICTURE and 
USAGE specifications. The compiler 
then generates code to manipulate the 
data based on the size of the field in 
storage (half word, etc.). TRUNC 
conforms to the American National 
Standard, while NOTRUNC leads to more 
efficient processing. This will 
occasionally cause dissimilar results 
for various sending fields because of 
the different code generated to 
perform the operation. 




ZWij 
NOZWB 



determines if the compiler will 
generate code to strip the sign when 
comparing a signed external decimal 
field to an alphanumeric field. If 
ZWB is in effect, the signed external 
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decimal field is moved to an 
intermediate field and has its sign 
stripped before being compared to the 
alphaniimeric field. ZVvB conforms to 
the ANS standard, while NOZWB allows 
the user to test input numeric fields 
for SPACES to prevent abnormal 
termination, 

SXREF 

NOSXREF 

causes the compiler to write an 
alphabetically-ordered cross-reference 
list on SYSLST. You may want to use 
the lister cross-reference information 
in place of this option for large 
COBOL programs, to decrease run time. 

PMAP=h 

enables the programmer to request a 
relocation factor "h". If the PMAP 
option is specified, the relocation 
factor is included in the addresses of 
the object code listing. The 
relocation factor "h" is a hexadecimal 
number of from one to eight digits. 
If the PMAP option is not specified, 
the relocation factor is assumed to be 
zero. When PMAP is specified in a 
segmented program, the listing for 
segments of priority higher than the 
segment limit (49, if the SEGMENT- 
LIMIT clause is not specified) , will 
not be relocated. The PMAP option 
has meaning only when LISTX or CLIST 
and/or SYM (for the location of WORKING- 
STORAGE) is in effect. 

OPTIMIZE 
NCOPTIMIZE 



one may be in effect during a given 

compilation. In addition, FLOW and 
STXIT are mutually exclusive at 
execution time. Additional 
information on the flow trace option 
can be found in the chapter "Symbolic 
Debugging Features." 



STATE 
NOSTATE 



OPT 
NOOPT 



OPTIMIZE (OPT) causes optimized object 

code to be generated by the compiler. 

The more efficient code generated con- Notes: 

siderably reduces the amount of space ' 

required by the object program. If ■^^ 

neither LINK nor DECK is specified in 

the OPTION statement, then optimized 

code is not generated by the compiler. 

This option cannot be used if either the 
symbolic debug option (SYMDMP) , the state- 
ment number option (STATE) , or the flow 
trace option (FLOW{=nn] ) is requested. 

FLOW[=nn] 

provides the programmer with a -formatted 2. 
trace (i.e., a list containing the pro- 
gram, identification and statement 
numbers) corresponding to a variable 
number of procedures executed prior to 
an abnormal termination. The value "nn" 
may range from through 99. If "nn" is 3. 
not specified, a value of 99 is assumed. 

FLOW and STXIT, and FLOW and OPT are 
mutually exclusive options, i.e., only 



STATE provides the prograirirer with 
information about the statement being 
executed at the time of an abnormal 
termination of a job. It identifies 
the program containing the statement 
and provides the number of the 
statement and of the verb being 
execut-ed. STATE and STXIT, STATE and 
SYMDMP, and STATE and OPT are mutually 
exclusive options, i.e., no more than 
one may be in effect during a given 
compilation. (However, the facilities 
provided by STATE automatically exist 
with SYMDMP.) In addition, STATE and 
STXIT are mutually exclusive at 
execution time. Additional 
information on the statement number 
option can be found in the chapter 
"Symbolic Debugging Features." 



SYNTAX, CSYNTAX, NOSYNTAX , 

indicates whether the source text is 
to be scanned for syntax errors only 
and appropriate error messages are to 
be generated. For conditional syntax 
checking (CSYNTAX) , a full compilation 
is produced so long as no messages 
exceed the C level. If one or more 
E-level or higher severity messages 
are produced, the compiler generates 
the messages but does not generate 
object text. 



When the SYNTAX option is in 
effect, all of the following 
compile- time options are 
suppressed: 

OPTION control statement: LINK, 
DECK, XREF 

CBL statement: SXREF, CLIST, 
COUNT, VERBREF, VERBSUM 

When CSYNTAX is requested and one 
or more D- or E-level messages 
occur,, then the preceding options 
are suppressed and the CBL option 
FLAGE is made active. 

Unconditional syntax checking is 
assumed if all of the following 
compile- time options are 
specified: 



< 
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OPTION control statement: NOLINK, 
NOXREF, NODECK 

CBL statement: SUPMAP.(and CLIST, 
SXREF, VERBSUM, and VERBREF are 
not specified) 

4. Some compiler diagnostics do not 
appear when SYNTAX or CSYNTAX is 
in effect. These are listed in 
"Program Checkout." 

SYMDMP [=f ilename] 

indicates to the compiler that 
execution— time dumps might bs 
requested for the program currently 
being compiled. If diHtips are desired, 
the programmer must provide the 
required control cards at execution 
time. For storage considerations at 
execution time, see Appendix F: 
"System and Size Considerations." 

Use of the symbolic debug option 
necessitates the presence of an ' 
additional work file, SYS005, at 
compile time. The "filename" 
parameter enables the programmer to 
specify a name for the SYS005 file 
that he can retain. If no filename is 
specified, IJSYS05 will be used. When 
several COBOL programs are link edited 
together, the "filename" parameter 
enables each to have a unique SYMDMP 
name. Compile and execution must be 
done in the same job stream. The 
SYS005 file is deleted at end of job. 
For a tape file, only unlabeled tapes 
may be used, and the filename in 
the SYMDMP=f ilename parameter is 
ignored. 

SYMDMP and STXIT, SYMDMP and STATE, 
and SYMDMP and OPT are mutually 
exclusive options, i.e., no more than 
one may be in effect during a given 
compilation. (However, the facilities 
provided by STATE are automatically 
included with SYMDMP.) In addition, 
SYMDMP and STXIT are mutually 
exclusive at execution-time. 
Additional information on the symbolic 
debug option and the required 
execution-time control cards can" be 
found in the chapter "Symbolic 
Debugging. Features." 

Note : If NODECK and NOLINK are requested 
on the OPTION control statement and either 
SYMDMP or OPT is specified on the CBL card, 
the SYMDMP or OPT specification is ignored. 

CATALR 

NOCATALR 

causes the compiler to generate CATALR 
card images on the SYSPCH file if 
OPTION DECK is in effect during 
compilation. This will allow 
cataloging of the compiler produced 
object modules into the relocatable 
library. The module names in the 
CATALR cards adhere to the same rules 
as the phase names in the compiler 



produced PHASE cards according to the 
segmentation and sort phase naming 
conventions (siee the sections on Sort 
and Segmentation Features). 

LIB 

NOLIB 

indicates that BASIS and/or COPY 
statements are in the source program. 
If either COPY or BASIS is present, 
LIB must be in effect. If COPY and/or 
BASIS statements are not present, use 
of the NOLIB option yields more 
efficient compiler processing. 

VERB 

NOVERB 

indicates whether procedure-names and 
verb- names are to be listed with the 
associated code on the object-program 
listing. VERB has meaning only if 
LISTX, CLIST, VERBSUM, VERBREF, COUNT 
or READY TRACE are in effect. NOVERB 
yields more efficient compilation. 



LVL= 



NOLVL 



indicates whether the compiler should 
identify COBOL clauses and statements 
in a DOS/VS COBOL source program that 
do not conform to the Federal 
Information Processing Standard. FIPS 
recognizes four language levels: low, 
low- intermediate , high- intermediate 
and full. The FIPS Flagger provides 
four levels of flagging from low (A) 
to high (D) to conform to the four 
levels of the FIPS. 

Note: The FIPS Flagger needs a disk 
workfile to be assigned to SYS006. 



i 



VERBSUM 
NOVERBSUM 



provides a brief summary of verbs used 
in the program and a count of how 
often each verb was used. This option 
provides the user with a quick search 
for specific types of statements. 
VERBSUM implies VERB. 



VERBREF 
NOVERBREF 



provides a cross reference of all 
verbs used in the program. This 
option provides the prograirmer with 
quick index to any verb used in the 
program. VERBREF implies VERB and 
VERBSUM. 



COUNT 
NOCOUNT 



generates code to produce verb 
execution summaries at the end of 
problem program execution. Each verb 
is identified by procedure-name and by 
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statement number, and the number of 
times it was used is indicated. In 
addition, the percentage of verb 
execution for each verb with respect 
to the execution of all verbs is 
given- A summary of all executable 
verbs used in a program and the number 
of times they are executed is 
provided. COUNT implies VERB. 

Note ; If COUNT and STXIT are desired, 
then either STXIT must be requested in 
the program unit requesting COUNT, or 
the program unit requesting COUNT must 
be entered before the program unit 
requesting STXIT. See the chapter 
entitled "Execution Statistics" for 
additional information on the COUNT 
option. 



requested, an updated and reformatted 
COPY library will be punched out. 

LSTONLY 

LSTCOMP 

when LSTONLY is specified, the prograir 
will not be compiled, but a 
reformatted listing will be produced 
along with a deck if DECK has been 
specified. LSTCOMP will provide a 
source listing and will compile the 
program as part of the job step. 
LSTCOMP does not suppress CLIST. 

PROC=lcol 
2col 

will list the Procedure Division in 
either single- or double-column 
format. At least 132 print positions 
are required on the printer for the 
double-column format. 



LST Statement — New Compiler Option Card 



The LST statement is used to invoke the 
lister, a portion of the compiler that 
processes programs written in American 
National Standard COBOL to produce a 
reformatted source code listing containing 
embedded cross-reference information, and 
uniform indenting conventions. 

The LST option card can be placed 
anywhere between the EXEC statement and the 
first statement of the COBOL program. It 
may be placed between any other compiler 
option cards. The options shown in the 
following format may appear in any order. 
Underscoring indicates the default case. 



jrOECK, irCOPYPCH, 1 ("LSTCOMP,] pROC= lcol ,li 
11 NODECK [[ nOCOPYPCh J [ LSTONLY | [_ 2col J| 
I I 



For more details on the lister program, 
see the chapter entitled "Using the Lister 
Feature". 



Mutually Exclusive Options 



In some of the preceding descriptions of 
the CBL card options, restrictions have 
been placed on the use of one option in 
conjunction with others. It should be 
noted that if these restrictions are 
violated, the compiler ignores all but the 
last of the conflicting options specified. 
For this reason, if after a CBL card is 
coded the programmer decides to use a new 
option that is mutually exclusive with an 
option on the original CBL card, a new CBL 
card can be added rather than changing the 
original card. 



Changing the Installation Defaults 



LST 



must begin in column 2 (column 1 must 
be blank) and be followed by at least 
one blank. 



DECK 
NODECK 



indicates whether an updated source 
deck is to be produced as a result of 
the lister reformatting and/or the 
update BASIS library. 



COPYPCH 

NOCOPYPCH 



will punch updated and reformatted 
copy libraries as a permanent part of 
the source when DECK is specified. 
When no updated source deck is 



In order to change the compiler default 
options to suit your installation, a new 
member, C.CBLOPTNS, must be added to the 
source statement library. This module must 
contain CBL option cards specifying the 
desired defaults. Resultant defaults may 
be overridden at compilation time by 
supplying a CBL card in the compiler input 
stream. 



Significant Characters for Various Options 



The DOS/VS COBOL compiler selects the 
valid options for processing by looking for 
three significant characters of each key 
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option word. When the keyword is 
identified, it is checked for the presence 
or absence of the prefix NO, as 
appropriate. The programmer can make the 
most efficient use of the CBL card by using 
the significant characters instead of the 
entire option. Table 3 lists the 
significant characters for each option. 



Table 



Significant 
Various Opt 



Characters for 
ions 



Option 



Significant 
Characters 



i SEQ 


I SEQ 




1 FLAGE(W) 


1 LAG,LAGW 




1 BUF 


BUF 




1 SPACE 


ACE 




1 ■ PMAP 


PMA 




1 SUPMAP 


SUP 




1 CLIST 


CLI 




1 TRUNC 


TRU 




1 APOST 


APO 




) QUOTE 


QUO 




1 SXREF 


SXR 




1 STATE 


STA 




1 FLOW 


FLO 




1 LIB 


LIB 




1 SYMDMP 


SYM 




1 OPTIMIZE 


OPT 




1 SYNTAX 


SYN 




1 CSYNTAX 


CSY 




1 VERB 


VER 




1 ZWB 


ZWB 




1 LVL 


LVL 




1 COUNT 


COU 




1 VERBSUM 


VERBSUM 




1 VEREREF 


VERBREF 




1 STXIT 


STX 




1 DECK 


DEC 




1 COPYPCH 


COP 




1 LSTCOMP 


STC 




1 LSTONLY 


STO 




1 PRoc ; 


PRO 




L : J 


1 


J 


Note: SYM on the CI 


JL card should not 


be 



confused with SYM on the OPTION card. 



JOB CONTROL COMMANDS 



Job control commands are distinguished 
from job control statements by the absence 
of // blank in positions 1 through 3 of 
each command. They permit the operator to 
adjust the system according to day-to-day 
operating conditions. This is particularly 
true in the area of device assignment, 
where the operator may need to 
(1) communicate to the system that a device 
is unavailable, or <2) designate a 
different device as the standard for a 
given symbolic unit. Therefore, these 
commands normally are not a part of the 



regular job deck for a job. Job control 
commands tend to be effective across jobs, 
whereas job control statements are confined 
within a job. 



Job control commands are discussed in 
detail in the publication DOS/VS System 
Control Statements. 



LINKAGE EDITOR CONTROL STATEMENTS 



Object modules used as input to the 
Linkage Editor must include linkage editor 
control statements. There are four linkage 
editor control statements: PHASE, INCLUDE, 
ENTRY, and ACTION. 



Linkage editor control statements 
initially enter the system through the 
device assigned to SYSRDR as part of the 
input job stream. PHASE and INCLUDE 
statements may also be present on SYSIPT or 
in the relocatable library. All four 
statements are verified for operation 
(INCLUDE, ACTION, ENTRY, or PHASE) and are 
copied to SYSLNK to become input when the 
Linkage Editor is executed. 

Linkage editor control statements must 
be blank in position 1 of the statement. 
The operand field is terminated by the 
first blank position. It cannot extend 
beyond column 72. 

The Linkage Editor is executed as a 
distinct job step. Figure 5 shows how the 
linkage editor function is performed as a 
job step in three kinds of operations. 

1. Catalog Programs in Core Image 

Library . The linkage editor function 
is performed immediately preceding the 
operation that catalogs programs into 
the core image library. When the 
CATAL option is spfrified, programs 
edited by the Linkage Editor are 
cataloged in the core image library by 
the Librarian after the editing 
function is performed. The sequence 
of this operation is shown in Part A 
of Figure 5- Note that the input for 
the LNKEDT function could contain 
modules from the relocatable library 
instead of, or in addition to, those 
modules from the card reader, tape 
unit- or mass storage unit extent 
assigned to SYSIPT. This is 
accomplished by naming the module^(s) 
to be copied from the relocatable 
library in an INCLUDE statement. 



i 
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2. Load-and-Execute . The sequence of 
this operation is shown in Part B of 
Figure 5. Specifying OPTION LINK 
causes the Job Control Processor to 
open SYSLNK, and allows the Job 
Control Processor to place the object 
module (s) and linkage editor control 
statements on SYSLNK. As with the 
catalog operation, the input can 
consist of object modules from the 
relocatable library instead of, or in 
addition to, those modules from the 
card reader, tape unit, or disk extent 
assigned to SYSIPT. This is accom- 
plished by specifying the name of the 
module to be included in the operand 
of an INCLUDE Statement. After the 
object modules have been edited and 
placed in the core image library, the 
program is executed. The blank 
operand in the EXEC control statement 
indicates that the program that has 
just been link edited and temporarily 
stored in the core image library is to 
be executed. 

3. Compile-and-Execute . Source modules 
can be compiled and then executed in a 



single sequence of job steps. In 
order to do this, the COBOL compiler 
is directed to write the object module 
directly on SYSLNK. This is done by 
using the LINK option in the OPTION 
control statement. Upon completion of 
this output operation, the linkage 
editor function is performed. The 
program is link edited and tem- 
porarily stored in the core image 
library. The sequence of this 
operation is shown in Part C of Figure 
5. 



In each of the operations described in 
Figure 5, if a private core image library 
is assigned, output from the Linkage Editor 
will be placed (either permanently or 
temporarily) in the private core image 
library rather than in the system core 
image library. If the Linkage Editor is 
executed in a batched- job foreground 
partition, a private core image library 
must be assigned- Private core image 
libraries are a system generation option. 



< 
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OPTION LINK 

EXEC FCOBOL 

ENTRY 

EXEC LNKEDT 

EXEC 



< 



Figure 5. Job Definition — Use of the Librarian 



Control Statement Placement 



The placement of linkage editor control 
statements is subject to the following 
rules: 



ACTION and ENTRY statements, when 
present, must be on SYSRDR. PHaSE and 
INCLUDE statements may be present on 
SYSRDR, SYSIPT, or in the relocatable 
library. 



1. The ACTION statement must be the first 
linkage editor control statement 
encountered in the input stream; 
otherwise, it is ignored. 



2. The PHASE statement must precede each 
object module that is to begin a 
phase. 



3. The INCLUDE statement must be 

specified for each object module that 
is to be included in a program phase- 



A single ENTRY statement should follow 
the last object module when multiple 
object modules are processed in a 
single linkage editor run. 



PHASE Statement 



The PHASE statement must be specified if 
the output of the Linkage Editor is to 
consist of more than one phase or if the 
program phase is to be cataloged in the 
core image library. Each object module 
that begins a phase must be preceded by a 
PHASE statement. Any object module not 
preceded by a PHASE statement will be 
included in the current phase. 

The statement provides the Linkage 
Editor with a phase name and an origin 
point for the phase. The PHASE statement 
is in the following format: 



PHASE name,origin[,NOAUTO] 
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is the symbolic name of the phase. It 
is the name under which the program 
phase is to be cataloged. This name 
does not have to be the name specified 
in the PROGRAM- ID paragraph in the 
Identification Division of the source 
program and, in the case of 
segmentation and/or sort, it should 
not be the same. It must consist of 
from one to eight alphanumeric 
characters. Phases that are to be 
executed in a segmentation and/or sort 
structure should have phase names of 
from five to eight alphaniimeric 
characters, the first four of which 
should be the same. An asterisk 
cannot be used as the first character 
of a phase name. If no phase name is 
specified, a dummy phase name of 
PHASE*** is used and execution stops 
at end of compilation. The job is 
then cancelled. 

origin 

indicates to the Linkage Editor the 
starting address of this specific 
phase. An asterisk may be used as an 
origin specification to indicate that 
this phase is to follow the previous 
phase. This origin specification 
format of the PHASE statement covers 
all applications that do not include 
setting up overlay structures. See 
the chapter "Calling and Called 
Programs" for information on the PHASE 
statement for overlay applications. 

NOAUTO 

indicates that the Automatic Library 
Look-Up (AUTOLINK) feature is 
suppressed for both the private 
relocatable library and the system 
relocatable library. (The use of 
NOAUTO causes the AUTOLINK process to 
be suppressed for that phase only. ) 
The AUTOLINK feature is discussed 
later in this chapter. 



INCLUDE Statement 



The INCLUDE statement must be specified 
for each object module deck o?: object 
module in the relocatable library that is 
to be included in a program phase. The 
format of the INCLUDE statement is as 
follows : 



INCLUDE [module-name] [, (namelist)] 



The INCLUDE statement has two optional 
operands. When both operands are used, 
they must be in the prescribed order. When 
the first operand is omitted and the second 



operand is used, a comma must precede the 
second operand. 

module-name 

must be specified when the object 
module is in the relocatable library. 
It is not specified when the module to 
be included is in the form of a card 
deck being entered from SYSIPT. 
module-name is the name under which 
the module was cataloged in the 
library, and must consist of from one 
to eight alphanumeric characters. 

(namelist) 

causes the Linkage Editor to construct 
a phase from the control sections 
specified in the list. Since control 
sections are of no interest to the 
COBOL programmer, users interested in 
this option should refer to the 
description of the INCLUDE statement 
in the publication DOS/VS System 
Control Statements. 



ENTRY Statement 



The ENTRY statement is required only if 
the programmer wishes to provide a specific 
entry point in the first phase produced by 
the Linkage Editor. When no ENTRY 
statement is provided, the Job Control 
Processor writes an ENTRY statement with a 
blank operand on SYSLNK to ensure that an 
ENTRY statement will be present to halt 
link editing. The transfer address will be 
the load address of the first phase. The 
ENTRY statement is described further in the 
publication DOS/VS System Control 
Statements. 



ACTION Statement 



The ACTION statement is used to indicate 
linkage editor options, when used, the 
statement must be the first linkage editor 
statement in the input stream. The format 
of the ACTION statement is as follows: 



ACTION 
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CLEAB 



MAP 



indicates that the entire temporary 
portion of the core image library will 
be set to binary zero before the 
beginning of the linkage editor 
function. CLEAR is a time-consuming 
function and should be used only when 
necessary. 



indicates that SYSLST is available for 
diagnostic messages. In addition, a 
storage map is output on SYSLST. 

NOMAP 

indicates that SYSLST is unavailable 
when performing the link edit 
function. The mapping of storage is 
not performed, and all linkage editor 
diagnostic messages are listed on 
SYSLOG. 

NOAUTO 

suppresses the AUTOLINK function for 
both the private and system 
relocatable libraries during the link 
editing of the entire program. 
AUTOLINK is discussed later in this 
chapter. 

CANCEL 

causes an automatic cancellation of 
the job if any of the linkage editor 
errors 21001 through 21701 occur. 
These diagnostic messages can be found 
in the publication D0S/7S System 
Control Statements . 

BG, F1, P2, P3, and F4 

are options used to link edit a 
program for execution in a partition 
other than that in which the link edit 
function is taking place. See the 
publication DOS/VS System Control 
Statements. 



NOREL 



suppresses the relocating loadfer. 



Link editing for a specific address is 
performed. 



AUTOLINK FEATURE 



If any references to external-names are 
still unresolved after all modules have 
been read from SYSLNK, SYSIPT, and/or the 
relocatable library, AUTOLINK collects each 
unresolved external reference from the 
phase. It then searches the private 
relocatable library (if SYSBLB has been 
assigned) and the system relocatable 
library for module names identical to the 
unresolved names and includes these modules 
in the program phase. This feature should 
not be suppressed (via PHASE or ACTION 
statements) in linkage editor job steps 
which include COBOL subroutines cataloged 
in the relocatable library. See the 
chapter "Calling and Called Programs" for 
additional details. 



RELOCATING LOADER FEATURE 



The relocating loader feature allows 
users to load single-phase and multi-phase 
programs at any valid problem program 
address in the system. Under this option, 
the linkage editor catalogs relocatable 
phases into the core image library, and the 
relocating loader in the supervisor assigns 
the absolute machine addresses that are 
necessary for program execution. This 
means the user need retain only one copy of 
the program in the core image library. 

The relocating loader is an optional 
feature, and must be specified at system 
generation time. 

Figure 6 illustrates options available 
during link-editing. 



■ 



Preparing COBOL Programs for Processing U3 




YES 



LINKAGE EDITOR 
PRODUCES 
RELOCATABLE 
PHASES 




LINKAGE-EDITING FOR A 
SPECIFIC PARTITION 

— Default: Addresses will be 
adjusted for the specified 
virtual partition. 

— Option: User may 
specify linking for 
the associated real 
partition. 



This supervisor cannot 
load relocatable phases. 
The user should specify 
ACTION=NOREL at 
link-edit time, or generate 
another supervisor with 
relocating loader. 



System retains flexibility of 
loading in any partition. 

Program may be included in 
job stream for any partition 
when program is loaded. 

— Default: Program runs 
in virtual mode. 

- Option: User may specify 
execution in associated 
real partition. 

Figure 6. Options Available During Link-Editing 
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LIBEARIAN FUNCTIONS 



DOS/VS supports four libraries: the 
:ore image library, the relocatable 
Library, the source statement library, and 
the procedure library. The core image, 
relocatable, and source statement libraries 
are classified as system libraries and 
private libraries. The procedure library 

system residence device (SYSRES) contains 
the system libraries. Private libraries 
can be contained on separate disk packs. 
These libraries are discussed under 
"Private Libraries" in this chapter. 
Executable programs (core image format) are 
stored in the core image library; 
relocatable object modules are stored in 
the relocatable library; source language 
routines are stored in the source statement 
library; catalogued procedures are stored 
in the procedure library. 



PLANNING THE LIBRARIES 



The components of the DOS/VS system are 
shipped in three system libraries: the 
core image library, the relocatable 
library, and the source statement library. 
A fourth library — the procedure library 
— is available but it does not contain any 
information when the system is shipped. 
Host programs and procedures developed and 
used by your installation will also be 
stored in these libraries. In addition to 
the system libraries, DOS/VS supports 
private libraries which you can use to 
either substitute for or supplement the 
corresponding system libraries. 



Planning the size, contents, and 
location of these libraries according to 
the needs of your installation is an 
essential part of the system generation 
procedure. Such detailed planning will 
ensure that: 



• No disk space is wasted by components 
not required in your installation. 



The libraries are large enough to allow 
for future additions. 

The libraries are accessed by the 
system with maximum efficiency. 



LIBRARIAN 

The Librarian is a group of programs 
that perform three major functions: 

1. Maintenance 

2. Service 



3. 



:opy 



Maintenance functions are used to 
catalog {that is, add) , delete, or rename 
components of the four libraries, condense 
libraries and directories, set a condense 
limit for an automatic condense function, 
reallocate directory and library extents, 
and update the source statement and 
procedure libraries. 

The copy function is used either to 
completely or selectively copy the disk on 
which the system resides. Service 
functions are used to translate information 
from a particular library to printed 
(displayed) or punched output. 

Only the catalog maintenance function of 
the Librarian is discussed in this 
publication for the four system libraries. 
In addition, the update function of the 
source statement library is discussed. A 
complete description of librarian functions 
can be found in the publication DOS/VS 
System Control Statements . 



CORE IMAGE LIBRARY 



The core image library may contain any 
number of programs. Each program consists 
of one or more separate phases. Associated 
with the core image library is a core image 
directory which contains a unique 
descriptive entry for each phase in the 
core image library. These entries in the 
core image directory are used to locate and 
retrieve phases from the core image 
library. 



Cataloging and Retievinq Program Phases — 
Core Image Library 



If a program is to be cataloged in the 
core image library, the job control 
statement // OPTION with the CATAL option 
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ssus't bs sP6ci.fi.sd. '^ri.or to ths f^^st 
linkage editor control card, and must 
precede the first PHASE card of the program 
to be cataloged. Upon successful 
completion of the linkage editor job step, 
output from the Linkage Editor is placed in 
the core image library as a permanent 
member. The program phase is cataloged 
under the name specified in the PHASE 
statement. 



If a phase in the core 
to be replaced by a new ph 
same name, only the catalo 
be used. The previously c 
the same name is implicitl 
the core image directory b 
function, and the space it 
library can later be relea 
condense function. 



image library is 
ase having the 
g function need 
ataloged phase of 
y deleted from 
y the catalog 

occupies in the 
sed by the 



Note : The necessary ASSGN control 
statements must follow the // JOB control 
statement if the current assignments are 
not the following: 

1. SYSBDR — Card reader, tape unit, or 

disk extent 

2. SYSIPT — Card reader, tape unit, or 

disk extent 

3. SYSLST — Printer, tape unit, or disk 

extent 

U. SYSLOG — Printer keyboard 

5. SYSLNK — Disk extent 

The following is an example of 
cataloging a single phase, FOORA, into the 
core image library. (The program phase 
POnEA can be executed in the next job step 
by specifying the // EXEC statement with a 
blank name field.) 

// JOB CATALOG 
// OPTION CATAL 

PHASE POURA,* 

INCLUDE 

{object deck) 

/* 

// LBLTYP TAPE 
// EXEC LNKEDT 
// EXEC 
/5 



To compile, link edit, and catalog the 
phase POURA into the core image library in 
the same job, the following job deck could 
be used: 



/* 

// EXEC LNKEDT 
/* 

/e 

When the phase is executed in a 
subsequent job, the EXEC statement that 
calls for execution must specify POURA, 
i.e., the name by which the phase has been 
cataloged. 

// JOB EXJOB 
// EXEC POURA 
/& 



Phases can be in eithe 
or relocatable format. T 
phases are loaded at the 
at link-edit time into a 
partition. The load addr 
constants of relocatable 
modified by the relocatin 
phases can be loaded at a 
different from the one fo 
link-edited. 



RELOCATABLE LIBRARY 



r non-relocatable 
he non -relocatable 
address computed 
real or virtual 
esses and address 
phases can be 
g loader. These 
virtual address 
r which it was 



The relocatable library contains any 
number of modules. Each module is a 
complete object deck in relocatable format, 
The purpose of the relocatable library is 
to allow the programmer to maintain 
frequently used routines in residence and 
combine them with other modules without 
recompiling. 

Associated with the relocatable library 
is the relocatable directory. The 
directory contains a unioue, descriptive 
entry for each module in the relocatable 
library. The entries in the relocatable 
directory are used to locate and retrieve 
modules in the relocatable library. 



MAINTENANCE FUNCTIONS 



To request a maintenance function for 
the relocatable library, the following 
control statement is used: 

// EXEC MA INT 



Cataloging a Module — Relocatable Library 



// JOB CATALOG 
// OPTION CATAL 

PHASE POURA,* 
// EXEC FCOBOL 



The catalog function adds a module to 
the relocatable library. A module in the 
relocatable library is the output of a 
complete COBOL compilation. 
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The catalog function implies a delete 
function- Thus, if a module exists in the 
relocatable library with the same name as a 
module to be cataloged, the module in the 
library is deleted by deleting reference to 
it in the relocatable directory. 

The CATALR control statement is required 
to add a module to the relocatable library. 
The format of the CATALR control statement 
is: 



CAtALk module-name [,v.mj 



module-name 

is the name by which the module is 
known to the control program. The 
module- name consists of from one to 
eight characters , the first of which 
must not be an asterisk, 

v.m 

specifies the change level at which 
the module is to be cataloged, v may 
be any decimal number from through 
127. m may be any decimal number from 
through 255. If this operand is 
omitted, a change level of 0.0 is 
assumed. A change level can be 
assigned only when a module is 
cataloged. 

All control statements required to 
catalog an object module must be read from 
SYSIPT. 

Note: If SYSRDR and/or SYSIPT are assigned 
to a tape unit, the MAINT program assumes 
that the tape is positioned to the first 
input record- The tape is not rewound at 
the end of the job. If a tape mark is 
found, MAINT assumes end-of-job. 



The following is an example of compiling 
a source program and cataloging the 
resultant module in the relocatable 
library. The job deck is read from SYSIPT. 

// JOB NINE 
// OPTION DECK 
// EXEC FCOBOL 



on SYSPCH- The next job step catalogs the 
object module (M0D9) into the relocatable 
library. Since the object module must be 
cataloged from SYSIPT, a message to the 
operator instructs him to place the object 
module on SYSIPT behind the CATALR 
statement. 

The following is an example of 
cataloging two rM-oT7-ir.iioiw r^i^c.^*-^^ 
modules in the 



Tne roiiowxng is an example or 
taloging two previously created object 
idules in the relocatable library: 



// JOB EIGHT 
// EXEC MAINT 
CATALR MOD 8 A 

{object deck} 

CATALR M0D8B 



{object deck} 






An additional capability of the system 
permits a programmer to compile a program 
and to catalog it to the system 
relocatable, or private relocatable, 
library in one continuous run. The 
programmer inserts a CATALR statement in 
his job control input stream preceding the 
compiler execute statement. The CATALR 
statement will be written on the SYSPCH 
file (tape or mass storage device) ahead of 
the compiler output when OPTION DECK is in 
effect. The programmer then reassigns the 
SYSPCH file as SYSIPT and executes the 
MAINT program to perform the catalog 
function. The output of the compilation 
(on tape or mass storage device) may be 
cataloged immediately or it may be 
cataloged at some later time. It can also 
be held after cataloging as backup of the 
compilation. 

The preceding method is recommended for 
single-module object decks. In programs 
for which the compiler produces multimodule 
object decks (when segmentation and/or SORT 
are being used) , it is necessary to use the 
CBL card CATALR option. This option causes 
a CATALR card to precede each object 
module. 
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{source deck} 
/♦ 

// PAUSE PLACE DECK AFTER CATALR CARD 
// EXEC MAINT 
CATALR MOD 9 



/* 



(punched deck goes here) 



In the above example, as a result of the 
compile step, the object module is written 



SOURCE STATEMENT LIBRARY 



The source statement library contains 
any number of books. Each book in the 
source statement library is composed of a 
sequence of source language statements. 
The purpose of the source statement library 
is to allow the COBOL programmer to 
initiate the compilation of a book into the 
source program by using the COPY statement 
or BASIS card. 
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Each book in the source statement 
library is classified as belonging to a 
specific sublibrary. Sublibraries are 
defined for three prograrr.itiing languages: 
Assembler, PL/I, and COBOL. Individual 
books are classified by sublibrary names. 
Therefore, books written in each of these 
languages may have the same name. 

Associated with the source statement 
library is a source statement directory. 
The directory contains a unique descriptive 
entry for each book in the source statement 
library. The entries in the source 
statement directory are used to locate and 
retrieve books in the source statement 
library. 



The operation field contains CATALS. 

sublib 

represents the sublibrary to which a 
book is to be cataloged and can be: 

Any alphanumeric character (0-9, A-Z, 
#, $, and a) representing source 
statement libraries. The characters 
A, C, E, and P have special uses: 

A and E are used for the Assembler 
sublibrary 

C is used for the COBOL sublibrary 

P is used for POWER in PL/I 



MAINTENANCE FUNCTIONS 



The sublib qualifier is required. If 
omitted, the operand will be flagged as 
invalid and no processing will be done on 
the book. 



To request a maintenance function for 
the source statement library, the following 
control statement must be used: 

// EXEC MAINT 



Cataloging a Book — Source Statement 



Library 



library-name 

represents the name of the book to be 
cataloged. The library-name consists 
of from one to eight alphanumeric 
characters, the first of which must be 
alphabetic. It is the name the 
programmer uses to retrieve the book 
when using the source language COPY 
statement or BASIS card. 



v.m 



The CATALS control statement is required 
to add a book to a sublibrary of the source 
statement library. 

A book added to a sublibrary of the 
source statement library is removed by 
using the delete function. When a book 
exists in a sublibrary with the same name 
as a book to be cataloged in that 
sublibrary, the existing book in the 
sublibrary is deleted. The following is 
the format of the CATALS control statement: 



specifies the change level at which 
the book is to be cataloged, v may be 
any decimal number from through 127; 
m may be any decimal number from 
through 255. If this operand is 
omitted, a change level of 0.0 is 
assumed. The v.m operand becomes part 
of the entry in the directory for the 
specified book. Its value is 
incremented each time an update is 
performed on the book. 



r 1 

I CATALS sublib. library-name [,v.mt,C] ] | 

L J 



indicates that change level 
verification is required before 
updates are accepted for this book. 
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See the UPDATE control statement, 
discussed later in this chapter, for its 
relationship to the v.m and C operands of 
the CATALS control statement. 

In addition to the CATALS control 
statement, a control statement of the 
following form must precede and follow the 
book to be cataloged: 



I BKEND [sublib. library-name ],[SEQNCZ], I 
I [count ],[CMPRSD] I 

I I 

All operand entries are optional. When 
used, the entries must be in the prescribed 
order and need appear only in the BKEND 
statement preceding the book to be 

cataloged . 

The first entry in the operand field is 
identical to the operand of the CATALS 
control statement. 

SEQNCE 

specifies that columns 76 to 80 of the 
card images constituting the book are 
to be checked for ascending sequence 
numbers. If an error is detected in 
the sequence checking, an error mes- 
sage is printed. The error can be 
corrected, and the book can be 
recataloged. 

count 

specifies the number of card images in 
the book. When the c ount operand is 
used, the card input is counted, 
beginning with preceding BKEND 
statement and including the subseguent 
BKEND statement. If an error is 
detected in the card count, an error 
message is printed. The error can be 
corrected, and the book can be 
recataloged . 

CMPFSD 

indicates that the book to be 
cataloged in the library is in 
compressed format as a result of 
CMPKSD having been specified when 
performing a PUNCH or DSPCK service 
function. These functions are 
described in the publication DOS/VS 
System Control Statements . 

Card input for the catalog function is 
from the device assigned to SYSIPT. The 
CATALS control statement is also read from 
the device assigned to SYSIPT. 

Frequently used Environment Division, 
Data Division, and Procedure Division 
entries can be cataloged in the COBOL 
sublibrary of the source statement library. 
A book in the source statement library 
might consist, for example, of a file 



description of the Data Division or a 
paragraph of the Procedure Division. 



The following is an example of 
cataloging a file description in the COBOL 
sublibrary of the source statement library 



// JOB ANYNAME 
// EXEC SAINT 

CATALS C.FILEA 
BKEND C.FILEA 

BLOCK CONTAINS 13 RECORDS 
RECORD CONTAINS 120 CHARACTERS 
LABEL RECORDS APE STANDARD 
DATA RECORD IS RECA . 
BKEND 
/* 
/& 



Retrieving a Cataloged Book — COBOL COPY 
Statement : The preceding file description 
can be included in a COBOL source program 
by writing the following statement: 

FD FILEB COPY FILEA. 

Note that the library entry does not 
include FD or the file-name. It begins 
with the first clause that is actually to 
follow the file-name. This is true for all 
options of the COPY statement. Kowever, 
data entries in the library may have a 
level number (01 or 77) identical to the 
level number of the data-name that precedes 
the COPY statement. In this case, all 
information about the library data-name is 
copied from the library and all references 
to the IJbrary data-name are replaced by 
the data-name in the program if the 
REPLACING option is specified. The change 
is made only for this program. The entry 
as it appears in the library remains 
unchanged. For example, assume the 
following data entry is cataloged under the 
library-name DATAR, 

01 PAYFILE USAGE IS DISPLAY. 
02 CALC PICTURE 99. 
02 GRADE PICTURE 9 

OCCURS 1 DEPENDING ON CALC OF 
PAYFILE. 

and the following statement is written in a 
COBOL source module: 

01 GROSS COPY DATAR REPLACING PAYFILE 
BY GROSS. 

The compiler interprets this as: 

01 GROSS USAGE IS DISPLAY. 
02 CALC PICTURE 99. 
02 GRADE PICTURE 9 

OCCURS 1 DEPENDING ON CALC OF 

GROSS. 
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BOte dioo una 4. cue 1 j.bi- ai. Y ~iiam e it; Used 
to identify the book in the library. It 
has no other use in the COBOL program. 

Text cataloged in the source statement 
library must conform to COBOL margin 
restrictions. 

The COBOL COPY statement is discussed in 
detail in the section "Extended Source 
Program Library Facility." 



bOOK I 

provides a temporary update option. 
The old book is renamed s. book 1 and 
the updated book is named 
sub lib . libra r y -name . s indicates the 
sublibrary that contains the old, 
renamed book. It may be one of the 
characters through 9, A through Z, 
#, $, or a). If this operand is not 
specified, the old book^ is deleted. 



Updating Books — Source Statement Library 



The update function is used to make 
changes to properly identified statements 
within a book in the source statement 
library. Statements are identified in the 
identification field, columns 73 through 
80, which is fixed in format as follows: 



Columns 73-76 



Columns 77-80 



Program identification 
which must be constant 
throughout the book. 

Sequence number of the 
statement within the 
book. 



One or more source statements may be 
added to, deleted from, or replaced in a 
book in the library without the necessity 
of replacing the entire book. The update 
function also provides these facilities: 

1. Resequencing statements within a book 
in the source statement library 

2. Changing the change level (v.m) of the 
book 

3. Adding or removing the change level 
requirement 

4. Copying a book with optional retention 
of the old book with a new name (for 
backup purposes) 

The UPDATE control statement is used for 
the update function and has the following 
format: 



UPDATE Eublib. library -na me, [ s.bookl ], | 
[v.m3,[nn] I 



The operation field contains UPDATE. 

sublib 

represents the sublibrary that 
contains the book to be updated. It 
may be any of the characters through 
9, A through Z, #, $, or S. 



nn 



represents the change level of the 
book to be updated. v may be any 
decimal number from through 127; m 
may be any decimal number from 
through 255. This operand must be 
present if change level verification 
is to be performed. Use of the 
optional entry C in the CATALS control 
statement at the time the book is 
cataloged in the library determines 
whether change level verification is 
required before updating. If the 
directory entry specifies that change 
level verification is not required 
before updating, the change level 
operand in the UPDATE control 
statement is ianored. 



If the change level is verified, the 
change level in the book's directory 
entry is increased by 1 by the system 
for verification of the next update. 
If m is at its maximum value and an 
update is processed, m is reset to 
and the value of v is increased by 1. 
If both V and m are at their maximum 
values and an update is processed, 
both V and m are reset to 0. 



represents the resequencing status 
required for the update. nn may be a 
1- or 2-character decimal number from 
1 throuqh ,0, or it may be the word 
HO. If nn is a decimal number, it 
represents the increment that will be 
used in resequencing the statements in 
the book. If nn is NO, the statements 
will not be resequenced. If nn is not 
specified, the statements will be 
resequenced with an increment of 1. 
When a book is resequenced, the 
sequence number of thefirst statement 
is 0000. For example, if a book is 
cataloqed in the source statement 
library with sequence numbers ranging 
from 0010 through 1000 with increments 
of 5 for each statement: 

and nn is not specified when the 
update function is performed, the book J 
is resequenced with numbers 0000, ^ 
0001, 0002, ... etc. 
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and NO is specified, insertions, 
deletions, and/or replacements are 
made with no effect on the original 
sequence numbers. 

and nn is specified as 2, the book is 
resequenced with numbers 0000, 0002, 
0004, ... etc., regardless of the 
original sequencing of the book in the 
library or the sequence numbers of the 
added or replacement cards. 



The UPDATE control statement is followed 
by ADD, DEL (delete) , and/or REP (replace) 
control statements as required, followed by 
the terminating END statement. The ADD, 
DEL, REP, and END statements are identified 
as update control statements by a right 
parenthesis in the first position (column 1 
in card format) . This is a variation from 
the general librarian control statement 
format; thus, it clearly identifies these 
control statements as part of the update 
function. 



ADD Statement : The ADD statement is used 
for the addition of source statements to a 



book, 



The format is: 



) ADD seq-no 



ADD indicates that source statements 
following this statement are to be added to 
the book. 

seq-no 

represents the sequence number of the 
statement in the book after which the 
new statements are to be added. It 
may be any decimal number consisting 
of from one to four characters. 

DEL Statement : The DEL statement causes 
the deletion of source statements from the 
book. The format is: 



t ) DEL first-seq-no[ ,last-seq-no] 



DEL indicates that statements are to be 
deleted from the book. 

first-seq-no 

last-seq-no 

represent the sequence numbers of the 
first and last statements of a section 
to be deleted. Each number may be a 
decimal number consisting of from one 
to four characters. If last-seq-no is 
not specified, the statement 
represented by first-seq-no is the 
only statement deleted. 



REP Statement : The REP statement is used 
when replacement of source statements is 
required in a book. The format is: 



I ) REP f irst-seq-no[ , last-seq-no] | 

I r 

REP indicates that source statements 
following this statement are to replace 
existing statements in a book. 

first-seg-no 

last-seq-no 

represent the sequence numbers of the 
first and last statements of a section 
to be replaced. Each number may be a 
decimal number consisting of from one 
to four characters. Any number of new 
statements can be added to a book when 
a section is replaced . (The number of 
statements added need not equal the 
number of statements being replaced.) 

Sequence number 9999 is the highest 
number acceptable for a statement to be 
updated. If the book is so large that 
statement sequence numbers have ''wrapped 
around" (progressed from 9998, 9999, to 
0000,0001), it will not be possible to 
update statements 0000 and 0001. 



END Statement : This statement indicates 
the end of updates for a given book. The 
format is: 



I ) END [v.m[ ,C]] 



v.m 



represents the change level to be 
assigned to the book after it is 
updated; v may be any decimal number 
from through 127. m may be any 
decimal number from through 255. 
This operand provides an additional 
means of specifying the change level 
of a book in the library. (The other 
method is through the use of the v.m 
operand in the CATALS statement.) 



indicates that change level 
verification is required before any 
subsequent updates for a given book. 

If v.m is specified and C is omitted, 
the book does not require change level 
verification before a subsequent update. 
This feature removes a previously specified 
verification requirement for a particular 
book. 

If both optional operands are omitted, 
the chanqe level in the book's directory 
entry is increased as a result of the 
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update, and the verification requirement 
remains unchanged. 



Control Statement Placement : Control 
statement input for the update function, 
read from the device assigned to SYSIN, 
must be in the following order: 



1. The JOB control statement, 



ADD, DEL, or RFP Statements ; 



1. If there is an invalid operation or 
operand in an ADD, DEL, or REP 
statement, the statement is flagged, 
the book is not updated, and the 
remaining control statements are 
checked to determine their validity. 
All options of the UPDATE and END 
statements are ignored. 



5. 

6. 
7. 
8. 



The ASSGN control statements, if the 
current assignments are not those 
required. The ASSGN control 
statements that can be used are SYSIN, 
SYSLST, and SYSLOG. 



The EXEC MAINT control statement. 

The DPDATE control statement. 

) ADD, ) DEL, or ) REP statements with 
appropriate source statements. 

) END statement. 

The /* control statement. 

The /S control statement, which is the 
last control statement of the job. 



The source statement library can also be 
updated by using the DELETE and INSERT 
cards. These are discussed in "Extended 
Source Program Library Facility" in this 
chapter, and in the publication IBM DOS 
Full American National Standard COBOL . 



PPDATE Function — Invalid Operand Defaults 



UPDATE Statement : 

1. If the first or second operand is 
invalid, the statement is flagged, the 
book is not updated, and the remaining 
control statements are checked to 
determine their validity. 

2. If change level verification is 
required and the incorrect change 
level is specified, the statement is 
flagged, the book is not updated, and 
the remaining control statements are 
checked to determine their validity. 

3. If the resequencing operand is 
invalid, resequencing is done in 
increments of 1. 



2. The second operand must be greater 

than the first operand in a DEL or REP 
statement. If not, the statement is 
considered invalid and is flagged, the 
book is not updated, and the remaining 
control statements are checked to 
determine their validity. All options 
of the UPDATE and END statements are 
ignored. 



3. All updates to a book between an 

DPDATE statement and an END statement 
must be in ascending sequential order 
of statement sequence numbers. The 
first operand of a DEL or REP 
statement oust be greater than the 
last operand of the preceding control 
statement. The operand of an ADD 
statement must be equal to or greater 
than the last operand of the preceding 
control statement. Consecutive ADD 
statements must not have the same 
operand. If these conditions are not 
met, the default is the same as for 
items 1 and 2. 



END Statement ; If the first operand of the 
END statement is invalid, the statement is 
flagged, both operands are ignored, and the 
book is updated as though no operands were 
specified. If the second operand is 
invalid, the statement is flagged, the 
operand is ignored, and the book is updated 
as though the second operand were not 
specified. 



Out-of -Sequence Updates : If the source 
statements to be added to a book are not in 
sequence or do not contain sequence 
numbers, the book is updated, and a message 
indicating the error appears following the 
END statement. If the resequencing option 
has been specified in the UPDATE statement, 
the book is sequenced by the specified 
value, and subsequent updating is possible. 
If the resequencing option is not 
specified, the book is resequenced in 
increments of 1, and subsequent updating 
will be possible. If the resequencing 
option NO is specified, the book will be 
out of sequence, and subsequent updating 
may not be possible. 



i 



52 



The Procedure Library 



Statement Format: 



The procedure library is a new system 
library that may be used to store — in 
card image format — 

• Frequently used sets, procedures, of 
job control and linkage editor 
statements (basic support). 

• Procedures additionally containing 
inline SYSIPT data, especially control 
stateinents for system utility and 
service programs (extended support) . 
The inline SYSIPT data must be 
processed under control of the 
device-independent sequential IOCS or 
by IBM- supplied service programs and 
language translators. 

The procedure library is part of SYSRES, 
so the maintenance and service functions 
available for the other DOS/VS libraries 
will also support the procedure library. 

Cataloged procedures may be included in 
the job control input stream by a job 
control statement and temporarily modified 
by overwrite statements. For more details 
on cataloged procedures, see DOS/VS System 
Control Statements. 



MAINT, PROCEDURE LIBRARY 



To request a maintenance function for 
the procedure library, use the following 
EXEC control statement: 

// EXEC MAINT 

One or more of the maintenance functions 
(catalog, delete, rename, condense, set 
condense limit, or reallocate) can be 
requested within a single run. Any number 
of procedures within the procedure library 
can be acted upon in this run. Further, 
one or more of the maintenance functions 
for either of the other three libraries 
(core image, source statement, or 
relocatable) can be requested within this 
run, for the same MAINT program maintains 
all four libraries. 



Catalog 



The control statement required to add a 
procedure to the procedure library is the 
CATALP statement. Any n\amber of procedures 
may be cataloged in a single run. Each 
procedure must immediately follow the 
respective CATALP statement. 



CATALP procedurenamet,VM=v.m] [,EOP=yy] 
NO 
, DATA=YES 

Each control statement in the procedure 
library should have a unique identity. 
This identity is required to modify the job 
stream at execution time. Therefore, when 
cataloging, identify each control statement 
in columns 73-79 (blanks may be embedded). 



represents the name of the procedure 
to be cataloged. The procedurename 
consists of one to eight alphameric 
characters, the first of which must be 
alphabetic. It must not be ALL. 

VM=v.m 

specifies the change level at which 
the procedure is to be cataloged, v 
may be any decimal number from 0-127. 
m may be any decimal number from 
0-255. If this operand is omitted, a 
change level of 0.0 is assumed. 

A change level can be assigned only 
when a procedure is cataloged. The 
change level is displayed and punched 
by the service functions. 

EOP=Yy 

specifies a two-character 

end-of -procedure delimiter. The EOP 

parameter can be any combination of 

characters except /*, /&, //; it must 

not contain a blank or a comma. The 

system assumes /+ as default 

end-of -procedure delimiter. Otherwise 

you can omit the EOP parameter. 

DATA=YES 

specifies that a procedure contains 
SYSIPT inline data. 

These procedures can only be executed 
in the extended procedure support. 

A procedure to be cataloged into the 
procedure library may consist of Job 
Control and linkage editor statements and, 
if the supervisor was generated with the 
SYSFIL option, additional control 
statements for IBM-supplied control and 
service programs and data processed under 
control of the device- independent 
sequential IOCS. The end of a procedure is 
indicated by the /+ end-of-procedure 
delimiter or by the end-of-procedure 
delimiter as specified in the EOP 
parameter. 

If SYSIN is assigned to a tape unit, the 
MAINT program assumes that the tape is 
positioned to the first input record. The 
tape is not rewound at the end of job. 
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control statement input for the catalog 
function, read from the properly assigned 
device (usually SYSIN) , is: 

1. the JOB control statement, followed by 

2. the ASSGN control statements, if the 
current assignments are not those 
required. The ASSGN statements that 
can be used are SYSIN, SYSLST, and 
SYSLOG. The ASSGN Statements are 
followed by 

3. the EXEC MAINT control statement, 
followed by 

4. the CATALP control statement (s) , 
followed by 

5. the module to be cataloged, followed 
by 

6. the /* control statement if other job 
steps are to follow, or 

7. the /£ control statement, which is the 
last control statement of the job. 



For example: 

// JOB CATPROC 



EXEC statement. Conversely, if the 
JOB statement is not cataloged, a JOB 
statement must precede the EXEC 
statement that retrieves the 
procedure. 

A cataloged procedure must not include 
any of the following control 
statements because they are not 
accepted when the procedure is 
processed: 



// ASSGN SYSRDR,X'cuu* 
// RESET SYS 
// RESET ALL 
// RESET SYSRDR 
// CLOSE SYSRDR, X'cuu* 
■// ASSGN SYSIPT,X'CUU'" 
// RESET SYSIPT 



// CLOSE SYSIPT, X'CUU' 



only if SYSIPT 
data is 
included 



4. Cataloged procedures cannot be nested, 
that is, a cataloged procedure cannot 
contain an EXEC statement that invokes 
another cataloged procedure. 

Note : Maintenance cannot be performed in 
the background partition on the procedure 
library while a foreground partition is 
using the library. 



ASSGN control statements, 
if required 



PSERV, PROCEDURE LIBRARY 



// EXEC MAINT 

CATALP PROCA , EOP=AA , DATA=YES 



To request a service function for the 
procedure library, use the following EXEC 
control statement: 



control statements 



// EXEC PSERV 



SYoIPT inline data 



/♦ END OF SYSIPT DATA 



One or more of the three service 
functions can be requested within a single 
run. Any number of procedures within the 
procedure library can be acted upon in this 
run. 



control statements 



CALLING CATALOGED PROCEDURES 



AA ElTD OF PROCEDURE 

The following restrictions apply when 
you catalog procedures to the procedure 
library: 

1. A cataloged procedure cannot contain 
control statements or SYSIPT data foi 
more than one job. 

2, If the cataloged control statements 
include the JOB statement, you must 
not have a JOB statement when you 
retrieve the procedure through the 



A cataloged procedure is called by a job 
that appears in the input stream or via an 
operator command. The job must consist of 
a JOB statement and an EXEC statement that 
specifies the cataloged procedure name. 
For example: 

// EXEC PROC=VCOBCLG 

The programmer can write cataloged 
procedures which incorporate job control he 
used frequently. For example, the 
programmer may wish to catalog a procedure 
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for compiling, link-editing, and executing U. 

a prograin. It is particularly useful for 

compiling in a low-priority test partition 

to which no card reader has been assigned. 

Using cataloged procedures, the operator 

can execute via the EXEC statement a 

cataloged procedure from the console. 5. 



Reference may be made to a private 
source statement library only if 
SYSSLB is assigned. If SYSSLB is 
assigned, the system source statement 
library cannot be changed. 

Private libraries cannot be 
reallocated. 



PRIVATE LIBRARIES 



The COPY function is not effective for 
private libraries except when they are 
being created. 



Private libraries are desirable in the 
system to permit some libraries to be 
located on a disk pack other than the one 
used by SYSRES. 

Private libraries are supported for the 
core image library, the relocatable 
library, and the source statement library, 
on the 2311, 2314, 2319, 3330, 3340, fixed 
block devices, and mass storage devices. 
However, the following restrictions apply: 

1. The private library m.ust be on the 
same type of disk device as SYSRES; 
the private core-image library can be 
on a type of device other than the one 
SYSRES is on. 



An unlimited nuirber of private libraries 
is possible. However, each must be 
distinguished by a unique file 
identification in the DLBL statement for 
the library. No more than one private 
relocatable library and one private source 
statement library may be assigned in a 
given job. 

The creation and maintenance of private 
libraries is discussed in the publication 
DQS/VS System Control Statements . 



Determinincr the Location of the Libraries 



Reference may be made to a private 
core image library only if SYSCLB is 
assigned. If SYSCLB is assigned, the 
system core image library cannot be 
changed. 

Reference may be made to a private 
relocatable library only if SYSRLB is 
assigned. If SYSRLB is assigned, the 
system relocatable library cannot be 
changed. 



Having decided which libraries you want 
in your system, you must determine where on 
the available devices these libraries are 
to be placed. All system libraries must 
reside in the SYSRES extent of the system 
disk pack in a predefined sequence (Figure 
7). Although it is theoretically possible 
to have private libraries on the system, 
pack (outside the SYSRES extent) , this is 
not recommended because it involves 
increased movement of the disk arm. 
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end of SYSRES extent 



Figure 7. The Relative Location of the Four System Libraries 



The directory area for each library is 
not shown in the Figure 7. By definition, 
all system libraries reside on the system 
residence file (SYSRES). If you have 
additional disk drives, you can define 
private core image, relocatable, and/or 
source statement libraries on the extra 
voluines. These volumes must be of the same 
type as the SYSRES pack. The system 
relocatable and system source statement 
libraries can be removed from SYSRES and 
established as private libraries; the 
system core image library, however, must 
always be present on SYSRES. It can be 
supplemented but not replaced by a private 
core image library. The procedure library 
is supported only as a system library; you 
cannot create a private procedure library. 



SOURCE LANGUAGE CONSIDERATIONS 



To use the private source statement 
library for COPY, BASIS, INSERT, and 
DELETE (see "Extended Source Program Library 
Facility" for further details), the ASSGN, 
DLEL, and EXTENT control statements that 
define this private library must be present 
in the job deck for compilation (unless 
they are permanently set up by the 
installation). When present, a search for 
the book is made in the private library. 
If it is not there, the system library is 
searched. If the statements for the 
private library are not present, the system 
library is searched. A programmer may 
create several private libraries, but only 
one private library can be used in a given 
job. 
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EXTENDED SOURCE PROGRAM LIBRARY FACILITY 



A complete program may be included as an 
entry in the source statement library by 
using the catalog function. This program 
can then be retrieved by a BASIS card and 
compiled in a subsequent job. 

The following control statements would 
be used to catalog the program SAMPLE as a 
book in the COBOL sublibrary of the source 
statement library: 

// JOB CATALOG 
// EXEC MAINT 

CATALS C. SAMPLE 

BKEND C. SAMPLE 



from the source statement library. The 
name of the program is PAYROLL. During a 
particular year, the old age insurance tax 
(FICA) is deducted at the rate of 4-2/555 
each week for all personnel until earnings 
exceed $7800. The coding to accomplish 
this is shown in Figure 8. 

Now, however, due to a change in the old 
age tax laws, tax is to be taken out until 
earnings exceed $10800 and a new percentage 
is to be placed. The programmer can code 
these changes as shown in Figure 9. 

The altered program will contain the 
coding shown in Figure 10. 



{source program) 
BKEND 



/* 
/g 



When compiling a program that has been 
cataloged in the COBOL sublibrary of the 
source statement library, a BASIS card 
brings in an entire source program. The 
following control statements could be used 
to compile the cataloged program SAMPLE: 

// JOB PGMl 

// OPTION LOG, DECK, LIST, LISTX, ERRS 

// EXEC FCOBOL 

CBL LIB 

BASIS SAMPLE 
/* 
/& 

INSERT or DELETE cards may follow the 
BASIS card if the user wishes to modify the 
book SAMPLE before it is processed by the 
compiler. The original source program must 
have been coded with sequence niambers in 
columns 1 through 6 of each source card. 

The INSERT statement will add new source 
statements after the specified sequence 
numbers. The DELETE statement will delete 
the statements indicated by the sequence 
numbers, or will delete more than one 
statement when the first and last sequence 
numbers to be deleted are specified, 
separated by a hyphen. Source program 
cards may follow a DELETE card for 
insertion before the card following the 
last one deleted. The sequence numbers in 
columns 1 through 6 are used to update 
COBOL source statements at compilation 
time, and are in effect for the one run 
only. 

Assume that a company runs its payroll 
program each week as a source program taken 



Reformatted Source Deck 



By specifying the DECK option on the LST 
card, a new COBOL source deck can be 
produced that reflects the reformatted 
source listing. This deck may be saved in 
a BASIS library, used directly as input to 
the compiler, or punched onto cards. 
Because of reformatting, the new deck may 
contain more cards than the original, but 
the difference is not great enough to cause 
any appreciable increase in compilation 
time. The output deck differs from the 
listing as follows: 

1. References, footnotes, and blank lines 
are omitted. 

2. Literals will be repositioned, if 
needed, to assure proper continuation. 

3. Statement numbers are converted to 
card numbers. 

a- The statement number is multiplied 
by 10, and leading zeros are added 
as necessary to fill columns 1 
through 6. 

b. Comment and continuation cards are 
numbered one higher than the 
preceding card. 

c. Statement-beginning cards are 
given the higher of the two 
numbers produced by the first two 
rules. 

The use of this feature avoids having to 
resequence cards for permanent updating 
after they have been tested by temporary 
updating using the BASIS feature; it also 
avoids the errors incurred during that 
resequencing process. 
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000730 IF ANNUAL-PAY GREATER THAN 7800 GO TO PAY-WRITE. 

000735 IF ANNUAL-PAY GREATER THAN 7800 - BASE-PAY GO TO LAST-FICA. 

000740 FICA-PAYR. COMPUTE FICA-PAY = BASE-PAY * .OHH 

000745 MOVE TAX- PAY TO OUTPUT-TAX. 

000750 PAY-WRITE. MOVE BASE-PAY TO OUTPUT-EASE. 

000755 ADD BASE-PAY TO ANNUAL- PAY, 



000850 STOP RUN. 

Figure 8. Sample Coding to Calculate FICA 



// JOB PGM2 

// OPTION LOG, DECK, LIST, LISTX, ERRS 

// EXEC FCOBOL 

CBL QUOTE, LIB 
BASIS PAYROLL 
DELETE 000730-000740 

000730 IF ANNUAL-PAY GREATER THAN 10800 GO TO PAY-WRITE. 
000735 IF ANNUAL-PAY GREATER THAN 10800 - BASE-PAY GO TO LAST-TAX. 
000740 TAX-PAYR. COMPUTE TAX-PAY = BASE-PAY ♦ .0585 
/* 

Figure 9. Altering a Program from the Source Statement Library Using INSERT and DELETE 
Cards 



j 000730 

1000735 

1000740 TAX-PAYR. 

1000750 

1000760 PAY-WRITE. 

1000770 

I . 



IF ANNUAL-PAY GREATER THAN 10800 GO TO PAY-WRITE. 

IF ANNUAL-PAY GREATER THAN 10800 - BASE- PAY GO TO LAST-TAX. 

COMPUTE TAX- PAY = BASE-PAY* .0585. 

MOVE TAX-PAY TO OUTPUT-TAX. 

MOVE BASE- PAY TO OUTPUT- BASE. 

ADD BASE-PAY TO ANNUAL- PAY. 



1000850 

L 



STOP RUN. 
Figure 10. Effect of INSERT and DELETE Cards 
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INTERPRETING OUTPUT 



The DOS/VS COBOL compiler, COBOL object 
ir.odule. Linkage Editor, and other system 
components can produce output in the form 
of printed listings, punched card decks, 
diagnostic or informative messages, and 
data files directed to tape or to mass 
storage devices. This chapter gives the 
format of and describes this output. The 
same COBOL program is used for each 
example. "Appendix A: Sample Program 
Output" shows the output formats in the 
context of a complete listing generated by 
the sample program- 



COMPILER OUTPUT 

The output of the compilation job step 
may include: 

• A printed listing of the job control 
statements 

• A printed listing of the statements 
contained in the source program 

• A glossary of compiler-generated 
information about data 

• Global tables, register assignments, 
and literal pools 

» A printed listing of the object code 

• A condensed listing containing only the 
relative address of the first generated 
instruction for each verb 

• Compiler statistics 

• Compiler diagnostic messages 

• Cross-reference listings 

• System messages 

• An object module 

• FIPS diagnostic messages 



The presence or absence of the 
above-mentioned types of compiler output is 
determined by options specified at system 
generation time. These options can be 
overridden or additional options specified 
at compilation time by using the OPTION 
control statement and the CBL card. 



The level of diagnostic message printed 
depends upon the FLAGW or FLAGE option of 
the CBL card. 



All output to be listed is written on 
the device assigned to SYSLST. If SYSLST 
is assigned to a magnetic tape, COBOL will 
treat the file as an unlabelled tape. Line 
spacing of the source listing is controlled 
by the SPACEn option of the CBL card and by 
SKIP 1/2/3 and EJECT in the COBOL source 
program. (The lister feature ignores these 
commands.) The number of lines per page 
can be specified in the SET command. In 
addition, a listing of input/output 
assignments can be printed on SYSLST by 
using the LISTIO control statement- 



On each page of the output, there is a 
header which contains the PROGRAM-ID, date 
and time of compilation,, as well as an 
indication of the m.odification level of the 
compiler which produced this listing. 



Figure 11 contains the compiler output 
listing shown in "Appendix A: Sample 
Program Output." Each type of output is 
numbered, and each format within each type 
is lettered. The text below and that 
following the figure is an explanation of 
the figure. 

(1) The listing of the job control 
statements associated with this job 
step . These statements are listed 
because the LOG option was specified 
at system generation time. 

(2) Compiler options . The CBL card, if 
specified, is printed on SYSLST unless 
the LIST option is suppressed, 

\3) The source module listing . The 

statements in the source program are 
listed exactly as submitted except 
that a compiler-generated card number 
is listed to the left of each line. 
This is the number referenced in 
diagnostic messages and in the object 
code listing. It is also the niamber 
printed on SYSLST as a result of the 
source language TRACE statement (if 
NOVERB is in effect) - The source 
module is not listed when the NOLIST 
option is specified. 
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// JCE SAMPLE ( ^T^ 

// OFIIOU NODECK,LJNK,LIS'I,LIiiaX,SyM,ERRS t \jj 
// EXEC FCOBOL .' 



IBM DOS VS COBOL 



REL 1.0 



PP NO. 5746-CBl 



07.43.04 03/03/74 



CEL QUOTE, OPT 
COOOl 000010 



C0002 


00002.0 


C0003 




ccooa 




00005 




00006 




00007 




C0008 




C0009 




00010 


000100 


00011 


000110 


00012 


000120 


00013 


000130 


00011 


000140 


00015 


000150 


00016 


000160 


00017 


000170 


00018 


000180 


n0019 


000190 



,SXREF,LVL=A Ci/ 
IDENTIFICATION DIVISION. 
PROGRAM- ID. TESTRON. 

AUTHOR. PROGRAMMER NAME.. 

INSTALLATION. NEW YORK DEVEIOEWENT CENTER 
DATE-WRITTEN. _FEBRUARY 18, 1974 
DATE -COMPILED. 03/U3/74 

REMARKS. THIS PROGRAM HAS BEEN WRITTEN AS A SAMPLE PROGRAM FOR 
COBOL USERS. IT CREATES AN OUTPUT FILE AND READS IT BACK 
AS INPUT. 

ENVIRONMENT DIVISION. 
CONFIGURATION SECTION. 
SOURCE-COMPUTER. IBM- 370. 
OBJECT-COMPUTER. IBM-370^ 
INPUT- OUTPUT SECTION. 
FILE-CONTROL. 

SELECT FILE-1 ASSIGN TO SYS008-DT-2400-S. 

SELECT FILE-2 ASSIGN TO SYS008-UT-2400-S. 



® 



00056 
C0057 
00058 
00059 
C0060 



000550 PROCEDURE DIVISION. 

BEGIN. 
000570 NOTE THAT THE FOLLOWING OPENS THE OUTPUT FILE TO BE CREATED 
000580 AND INITIALIZES COUNTERS. 
000590 STEP-1. OPEN OUTPUT FILE-1. MOVE ZERO TO KOUNT, iWMBR. 



C0073 000720 STEP-5. CLOSE FILE-1. OPEN IN. 

C0074 000730 NOTE THAT THE FOLLOWING READa HACK THE FILE AND SINGLES 

00075 000740 OUT EMPLOYEES WITH HO DEPENDENTS. 

C0076 000750 STEP-6. READ FILE-2 RECORD INTO WORK-RECORD AT END GO TO STEP-8. 

00077 000760 STEP-7. IF NO-OF-DEPENDENTS IS EQUAL TO "0" MOVE "Z" TO 

00078 000770 NO-CF-DEPENDENTS. EXHIBIT NAKED WORK-RECORD. GO TO STEP-6. 

00079 000780 STEP-8. CLOSE FILE-2. 

00080 000790 STOP RUN. 
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IM4 DOS VS COBOL 



PP KO. 5746-CBl 



07.43.04 10/03/73 



® 



© 



INTRNL NAME 


LVL 


SOURCE NAME 




DNM=1-1118 


FD 


FILE-1 




DSM= 1-179 


01 


RECORD- 1 




DNM=l-200 


02 


FIELD-A 




DNM=1-217 


FD 


FILE-2 




DNM=l-2<»8 


01 


RECORD- 2 




DlIM=l-269 


02 


FIELD-A 




DIlM=l-289 


01 


FILLER 




DNM=l-308 


02 


KOUNT 




DNM=l-323 


02 


ALPHABET 




DHM=l-3ai 


02 


ALPHA 




DNM=l-359 


02 


NUMBR 




DNM=l-37It 


02 


DEPENDENTS 




DKM=1-39U 


02 


DEPEND 




DI)M=1-«10 


01 


WORK-RECORD 




DNM=l-«3* 


02 


NAME-FIELD 




DNM=1-U5H 


02 


FILLER 




DNM=l-473 


02 


RECORD- NO 




DNM=l-«92 


02 


FILLER 




DNK=2-000 


02 


LOCATION 




DHK=2-01S 


02 


FILLER 




DNM=2-037 


02 


NO-OF-DEPENDENTS 




DNM=2-063 


02 


FILLER 
MEMORY HAP 






TGT 


© 


003F8 


SAVE 


AKEA 




003F8 


SWITCH 




00440 


TALLY 




00444 


SORT 


SAVE 




00448 


ENTRY- SAVE 


004 4C 


SORT 


CORE 


SIZE 


00450 


NSTD 


-REELS 


00454 


SORT 


RET 




00456 


HCRKING CELLS 


00458 


SORT 


FILE 


SIZE 


00588 


SORT 


MODE 


SIZE 


0058C 


PGT-VN TBL 


00590 


TGT-VN TBL 


00594 


SORTAB ADDRESS 


00598 


LENGTH OF 


VN TBL 


0059C 


LNGTH OF 


SORTAB 


0059E 


PGM ID 




005A0 


AdNITl) 




005A8 


UPS I 


SWITCHES 


005AC 


DEBUG TABLE PTR 


005B4 


CURRENT PRIORITY 


005B8 


TA LENGTH 




005B9 


FR3L1 CELL PTR 


005EC 


UNUSED 




005C0 


RESERVED 




005C4 


VSAK 


SAVE 


AREA ADDRESS 


005C8 


UNUSED 




005CC 


RESERVED 




005D4 


OVERFLOW 


CELLS 


005EC 


BL CELLS 




005EC 


DTFADR CELLS 


005F8 


FIB CELLS 




00600 


TEMP 


STORAGE 


00608 


TEMP 


STORAGE- 2 


00610 


TEMP 


STORAGE- 3 


00610 


TEMP 


STORAGE-* 


00610 


BLL CELLS 




00610 


VXC CELLS 




00614 


SBL CELLS 




00614 


INDEX CELLS 


00614 


SDBADB CELLS 


00614 


ONCTL CELLS 


0061C 


PFMCTL CELLS 


0061C 


PFMSAV CELLS 


0061C 


VN CELLS 




00620 


SAVE 


AREA 


=2 


00624 


XSASW CELLS 


00624 



® © 



® ® 



© 



BASE 


DISPL 


INTRNL NAME 


DEFINITION 


JSAGE 


DTF=01 




DNK=1-148 






DTFMT 


BL=1 


000 


DN«=1-179 


DS 


0CL2C 


GROUP 


BL=1 


000 


DNM=l-200 


DS 


20C 


DISP 


DTF=02 




DNM=1-217 






DTF*iT 


BL=2 


000 


DNM=l-248 


OS 


0CL20 


GROUP 


BL=2 


000 


DHM=l-269 


DS 


20C 


DISP 


BL=3 


000 


DNM=l-289 


DS 


0CL56 


GROUP 


BL=3 


000 


DNM=l-308 


DS 


IH 


COfriP 


BL=3 


002 


DNM=l-323 


DS 


26C 


DISP 


BL=3 


002 


DNH=1-341 


DS 


IC 


DISP 


BL=3 


OIC 


DNM=l-359 


DS 


IH 


COMP 


BL=3 


OlE 


DNM=l-374 


DS 


26C 


DISP 


BL=3 


OlE 


DNM=l-394 


DS 


IC 


DISP 


BL=3 


038 


DNM=1-410 


DS 


0CL20 


GROUP 


BL=3 


038 


DNM=l-434 


DS 


IC 


DISP 


BL=3 


039 


DNM=l-454 


DS 


IC 


DISP 


BL=3 


03A 


DNM=l-473 


DS 


4C 


DISP-NK 


BL=3 


03E 


DNM=l-492 


DS 


IC 


DISP 


BL=3 


03F 


DNM=2-000 


DS 


3C 


DISP 


BL=3 


042 


DNM=2-018 


DS 


IC 


DISP 


BL=3 


043 


DNM=2-037 


DS 


2C 


DISP 


BL=3 


045 


DNM=2-063 


DS 


7C 


DI£F 



© 



LITERAL POOL (HEX) 



© 



0C64O (LIT+0) 
00658 (LIT+24) 



00000001 001A5B5B C2D6D7C5 D5405B5B G2C3D3D6 E2C55B5E 
C2C6C3D4 E4D35B5B COOOOOOO 



DISPLAY LITERALS (BCD) 
00664 (LTL+36) "WORK-RECORD' 



PGT 



© 



DEBUG LINKAGE AREA 
OVERFLCH CELLS 
VIRTUAL CELLS 
PROCEDURE NAME CELLS 
GENERATED NAME CELLS 
SUBDTF ADDRESS CELLS 
VNI CELLS 
LITERALS 

DISPLAY LITERALS 
PROCEDURE BLOCK CELLS 



00628 

00628 
00628 
0062C 
00638 
00638 
00e3C 
006 3C 
00640 
00664 
00670 



Figure 11. Examples of Compiler Output (Part 2 of 4) 
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IBM DOS VS COBOL 



REL 1.0 



PP NO. 5746-CBl 



07.43.04 TO/03/73 



SEGISTER ASSIGNMENT 



REG 6 
REG 7 
REG 8 



BL 
BL 
BL 



® 



WOBKING-STORAGE STARTS AT LOCATION 00100 FOR A LENGTH OF 00050. (5J 
PROCEDURE BLOCK ASSIGNMENT ^ 



PBL = REG 11 



PEL =1 STARTS AT LOCATION 000674 

© ® © 



STATEMENT 60 



© 



© 







000674 














PN= 


=02 


EQU 


* 








60 
































60 




000674 














PN= 


= 03 


EQU 


* 










000674 














START 


EQU 


* 












000674 


58 


BO 


C 


048 










L 


11,048(0,12) 


PBL=1 










000678 


58 


20 


D 


1F4 










L 


2,1F4(0,13) 


BL =1 










00067C 


41 


10 


C 


OlE 










LA 


1,01E(0,12) 


LIT+6 










000680 


58 


00 


D 


200 










L 


0,200(0,13) 


DIF=1 










000684 


18 


40 














LR 


4,0 












000686 


05 


FO 














BALR 


15,0 












000688 


50 


00 


F 


008 










ST 


0,008(0,15) 












00068C 


45 


00 


F 


OOC 










BAL 


0,00C(0,15) 












000690 


00000000 










DC 


X'OOOOOOOO' 












000694 


OA 


02 














SVC 


2 












000696 


41 


00 


D 


200 










LA 


0,200(0,13) 


DTF=1 










00069A 


58 


FO 


C 


008 










L 


15,Q08(0,12) 


V(ILEDIMLO) 










00069E 


05 


EF 














BALR 


14,15 












0006AO 


58 


10 


D 


200 










L 


1,200(0,13) 


DTF=1 










0006A4 


96 


10 


1 


020 










01 


020(1), X'lO- 












0006A8 


50 


20 


D 


1F4 










ST 


2,1F4(0,13) 


EL =1 






60 




0006AC 


58 


70 


D 


1F4 










L 


7,1F4(0,13) 


BL =1 








0OO6B0 


D2 


01 


6 


000 


C 


018 


/- 


^ 


MVC 


000(2, 6), 018(12) 


DNM=l-308 


LIl+O 




61 
6t 




0006B6 


D2 


01 


6 


OIC 


C 


018 


(L* 


MVC 


01C(2, 6), 018(12) 


DNM=l-359 


LI1 + 






0006BC 














PN= 


= 04 


EQU 


* 










0006BC 


48 


30 


C 


OlA 










LH 


3,01A(0,12) 


IIT+2 










0006C0 


4A 


30 


6 


000 










AH 


3,000(0,6) 


DNM=l-308 










0006C4 


4E 


30 


D 


210 










CVD 


3,210(0,13) 


TS=01 










0006C8 


D7 


05 


D 


210 


D 


210 






XC 


210(6, 13), 210(13) 


TS=01 


TS=01 








0006CE 


94 


OF 


D 


216 










NI 


216(13) ,X'0F' 


TS=01+6 










0006D2 


4F 


30 


D 


210 










CVB 


3,210(0,13) 


TS=01 










0006D6 


40 


30 


6 


000 










STH 


3,000(0,6) 


DNM=l-308 










0006DA 


48 


30 


C 


OlA 










LH 


3,01A(0,12) 


LlT+2 










0006DE 


4A 


30 


6 


OIC 










AH 


3,01C(0,6) 


DNM=l-359 










0006E2 


4E 


30 


D 


210 










CVD 


3,210(0,13) 


TS=01 










0006E6 


D7 


05 


D 


210 


D 


210 






XC 


210(6,13), 210(13) 


TS=01 


TS=01 








0006EC 


94 


OF 


D 


216 










NI 


216(13), X'OF- 


TS=01+6 










0006F0 


4F 


30 


D 


210 










CVB 


3,210(0,13) 


TS=01 






64 




0006F4 


40 


30 


6 


OIC 










STH 


3,01C(0,6) 


DNM=l-359 








0006F8 


41 


40 


6 


002 










LA 


4,002(0,6) 


DNM=1-341 










0006FC 


48 


20 


6 


000 










LH 


2,000(0,6) 


DNM=l-308 










000700 


4C 


20 


C 


OlA 










MH 


2,01A(0,12) 


LIT+2 










000704 


lA 


42 














AR 


4,2 












000706 


5B 


40 


C 


018 










S 


4,018(0,12) 


LIT+0 










00070A 


50 


40 


D 


21C 










ST 


4,21C(0,13) 


SBS=1 










00070E 


58 


EO 


D 


21C 










L 


14,21C(0,13) 


SBS=1 
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000712 


D2 


00 


6 


038 


E 


000 






MVC 


038 (1,6), 000(14) 


DNM=l-434 


DNM=1-341 








000718 


41 


40 


6 


OlE 










LA 


4,01E(0,6) 


DNM=l-394 










00071C 


48 


20 


6 


000 










LH 


2,000(0,6) 


DNM=l-308 










000720 


4C 


20 


C 


OlA 










MH 


2,01A(0,12) 


LIT+2 










000724 


lA 


42 














AR 


4,2 












000726 


5B 


40 


C 


018 










S 


4,018(0,12) 


LIT+0 










00072A 


50 


40 


D 


220 










ST 


4,220(0,13) 


SBS=2 










00072E 


58 


FO 


D 


220 










L 


15,220(0,13) 


SBS=2 










000732 


D2 


00 


6 


043 


F 


000 






MVC 


043(1.6) ,000(15) 


DNM=2-37 


DNM=l-394 








000738 


92 


40 


6 


044 










MVI 


044(6), X'40' 


DNM=2-37+l 






♦STATISTICS* 


SOURCE : 


RECORDS = 




80 






DATA ITEMS = 22 KG OF 


VERBS = 28 






♦STATISTICS* 


PARTITION ; 


SIZE = 


655176 






LINE COUNT = 56 BUFFEP 


! SIZE = 512 






*OPTIONS 


IN EFFECT* 


PMAP 


' RELOC 


ADR = 




NONE 






SPACING 


1 FLOW 


NONE 






♦OPTIONS 


IN EFFECT* 


LISTX 




QUOTE 






SYM HOCATALR LIST 


LINK NCSTXIT 


NCLIB 


♦OPTIONS 


IN EFFECT* 


NOCLIST 




FLAGW 






ZWB NOSUPMAP XREF 


ERRS 


SXREF 


OPT 


♦OPTIONS 


IN EFFECT* 


NOSTATE 




TRUNC 






SEQ NOSYNDMP NCDECK 


NCVEHE NCSYNTAX 


LVL=A 







® 



Figure 11. Examples of Compiler Output 
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im DOS VS COBOL 



© 



DATA NAMES 



REL 1.0 PP NO. 5746-CBl 

CROSS -HEFERENCE DICTIONARY 

REFERENCE 



07.43.04 03/03/74 



ALPHA 

AIPHABET 

DEPEND 

DEPENDENTS 

FIELD- A 

FIELD-A 

FILE-1 

FILE-2 

KCUNT 

LOCATION 

NAME-FIELD 

NC-CF-DEPENDENTS 

NOMBR 

RECORD- NO 

RECORD- 1 

RECORD- 2 

WORK-RECORD 



000042 
000041 
000045 
000044 
000029 
000037 
000017 
000018 
000040 
000051 
000047 
000053 
000043 
000049 
000028 
000036 
000046 



000064 
000066 



000060 000068 000073 
000073 000076 000079 
000060 000064 000066 000070 

000064 

000066 000077 

000060 000064 000067 

000067 

000068 

000076 

000068 000076 000078 



® 



® 



PROCEDURE NAMES 



BEGIN 
STEP-1 
STEP- 2 
STEP- 3 
STEP-4 
STEP- 5 
STEP- 6 
3TEP-7 
STEP- 8 



000057 
000060 
000064 
000068 
000070 
000073 
000076 
000077 
000079 



000070 
000070 



000076 



—^ CARD ^-£RROR MESSAGE/TN 
^-^ 00064^-T:LA'^niiT_u-*^ u- 



® 



LA6011I-W'' HIGH ORDER TRUNCATION MIGHT OCCUR. 
00064 ILA5011I-W HIGH ORDER TRUNCATION MIGHT OCCUR. 



® 



FEDERAL INFORMATION PROCESSING STANDARDS (FIPS) DIAGNOSTIC MESSAGES 



^,1-INE/- 


•>JJUMBER (^ 


^ V? 


>^ ^^ 


^coooe^ 


ia8003I-W 


00025 


ILA8002I-W 


00034 


ILA8002I-W 


C0C54 


ILA8003I-W 


C0060 


ILA8003I-W 


C0C62 


ILA8003I-W 


C0062 


ILA8003I-W 


C0064 


ILA8003I-W 


00064 


ILA8003I-W 


00068 


ILA8003I-W 


C0068 


ILA8002I-W 


C0068 


ILA8003I-W 


C0070 


ILA8003I-W 


C0076 


ILA8003I-W 


C0078 


ILA8002I-W 



MESSAGE 



END OF COMPILATION 



® 



DATE-COMPILED PARAGRAPH IS AN EXTENSION TO FIPS LEVEL A. 

RECORDING MODE IS CLAUSE IS AN EXTENSION TO ALL FIPS LEVELS. 

RECORDING MODE IS CLAUSE IS AN EXTENSION TO ALL FIPS LEVELS. 

SPACES IS AN EXTENSION TO FIPS LEVEL A. 

COMMA OR SEMICOLON AS PUNCTUATION IS AN EXTENSION TO FIPS LEVEL A. 

COMMA OR SEMICOLON AS PUNCTUATION IS AN EXTENSION TO FIPS LEVEL A. 

COMMA OR SEMICOLON AS PUNCTUATION IS AS EXTENSION TO FIPS LEVEL A. 

COMMA OR SEMICOLON AS PUNCTUATION IS AN EXTENSION TO FIPS LEVEL A. 

MULTIPLE RESULTS IN ADD STATEMENT IS AN EXTENSION TO FIPS LEVEL A. 

UPON OPTION OF DISPLAY STATEMENT IS AN EXTENSION TO FIPS LEVEL A. 

UPON CONSOLE OPTION OF DISPLAY STATEMENT IS AN EXTENSION TO ALL LEVELS. 

FROM OPTION OF HRITE STATEKENT IS AN EXTENSION TO FIPS LEVEL A. 

UNTIL OPTION OF PERFORM STATEMENT IS AN EXTENSION TO FIPS LEVEL A. 

INTO OPTION OF READ STATEKENT IS AN EXTENSION TO FIPS LEVEL A. 

EXHIBIT STATEMENT IS AN EXTENSION TO ALL FIPS LEVELS. 



) ® 






Figure 11. Examples of Compiler Output (Part 4 of U) 
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The following notations iray appear on 
the listing: 

C Denotes that the statement was inserted 
with a COPY statement. 

*♦ Denotes that the card is out of 

sequence. NOSEQ should be specified on 
the CBL card if the sequence check is 
to be suppressed. 

I Denotes that the card was inserted with 
an INSERT or BASIS card. 

If DATE-COMPILED is specified in the 
Identification Division, any sentences in 
that paragraph are replaced in the listing 
by the date of compilation. It is printed 
in one of the following formats depending 
upon the format chosen at system generation 
time. 

DATE- COMPILED, month/day/year or 

DATE- COMPILED. day /month/year 

(u) Glossary . The glossary is listed 
when the SYM option is specified. 
The glossary contains information 
about names in the COBOL source 
program. 

(a) and^r) The internal-name 

generated by the compiler. 
This name is used in the 
compiler object code listing 
to represent the name used in 
the source program. It is 
repeated in column F for 
readability. 

\b) a normalized level number. 
This level number is 
determined by the compiler as 
follows: the first level 
number of any hierarchy is 
always 01, and increments for 
other levels are always by 
one. Only level numbers 03 
through 49 are affected; 
level numbers 66, 77, and 88, 
and FD, SD, and RD indicators 
are not changed. 



TER.COD 



FRS- GEN 



RPT- RCD 



CTL- CHR 



RPT- LIN 



© 



The data-name that is used in 
the source module. 



Used by coding for 
TERMINATE clause. 

Used by coding for 
GENERATE clause. 

Generated report record 
associated with the file 
on which the report is 
to be printed. 

Build area for print 
record. 

First or second position 
of RPT. RCD. Used for 
carriage control 
character. 

Beginning of actual 
information which will 
be displayed. Second or 
third position of 
RPT. RCD. 

Used to hold code 
specified. 

Name generated from 
COLUMN clause in 
02- level statement. 

Used for elementary 
level with SUM clause, 
but not with data-name. 

Used to save the total 
number of lines used by 
a report group when 
relative line numbering 
is specified. 

(d) and^E) For data-names, these columns 
contain information about the 
address in the form of a base and 
displacement. For file- names, the 
column contains information about 
the associated DTF or FIB (for 
VSAM) . An indication is also 
given here if the FD is invalid. 

(g) This column defines storage for 

each data item. It is represented 
in assembler-like terminology. 
Table 4 refers to information in 
this column. 



CODE- 
CELL 

E.nnnn 



S.nnnn 



N.nnnn 



Note: The following Report Writer 
internally-generated data-names 
can appear under the SOURCE NAME 
column: 



CTL.LVL Used to coordinate 
control break 
activities. 

GRP.IND Used by coding for GROUP 
INDICATE clause. 



Usage of the data-name. For FD 
entries, either VSAM is specified, 
or the DTF type is identified 
(e.g., DTFDA) . For group items 
containing a USAGE clause, the 
usage type is printed. For group 
items that do not contain a USAGE 
clause, GROUP is printed. For 
elementary items, the information 
in the USAGE clause is printed. 
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Table 4. Glossary Definition and Usage 

r T 

1 Type I 

^ + 



Definition 



Usage 



GROUP 
DISP 
DISP 
AN- EDIT 
NM-EDIT 
INDEX-NM 
GROUP 
RPT-ST 
DISP-NM 
DISP-FP 
COMP-1 
COMP-2 
OR 2F i COMP 

COMP-3 
DISP-ST 
INDEX-NAKE 
DTF TYPE 
BLANK 
BLANK 
BLANK 
i X 

Note : Under the definition column, N = size in bytes, except in group variable-length 
where it is a variable cell number. 

L J 



Group Fixed-Length 


DS 


OCLN 


Alphabetic 


DS 


NC 


Alphanumeric 


DS 


NC 


Alphaniameric Edited 


DS 


NC 


Numeric Edited 


DS 


NC 


Index-Name 


DS 


IH 


Group Variable-Length 


DS 


VLI=N 


Sterling Report 


DS 


NC 


External Decimal 


DS 


NC 








riXucincix xo-vjcii — Ljiiy £<_>-i.ii'C 






Internal Floating-Point 


DS 


IF 




DS 


ID 


Binary 


DS 


IH, 1 


Internal Decimal 


DS 


NP 


Sterling Non-Report 


DS 


NC 


Index-Name 


BLANK 


File (FD) 


BLANK 


Condition (88) 


BLANK 


Report Definition (RD) 


BLANK 


Sort Definition (SD) 


BLANK 



(^ A letter under column: 



© 



© 



R - Indicates that the data-name 
redefines another data-name. 

O - Indicates that an OCCURS 

clause has been specified for 
that data-name. 

Q - Indicates that the data-name 
is or contains the DEPENDING 
ON object of the OCCURS 
clause. 

M - Indicates the record format. 
This field is not applicable 
to VSAM. The letters which 
may appear under coliamn M are: 

F - fixed-length records 

U - undefined records 

V - variable- length records 

S - spanned records 

The location and length of WORKING- 
STORAGE are noted here when CLIST, 
SYM or LSTX is specified, except under 
the same conditions as noted below. 



Global tables and literal pool : 
Global tables and the literal pool are 
listed when the CLIST, SYM, or LISTX 
option is specified, unless SUPMAP is 
specified and an E-level error is 



encountered, or CSYNTAX is specified 
and an E-level error is encountered. 
A global table contains easily 
addressable information needed by the 
object program for execution. For 
example, in the Procedure Division 
output coding (3) , the address of the 
first instruction under STEP-1 (OPEN 
OUTPUT FILE-1) is found in the 
PROCEDURE NAME CELLS portion of the 
Program Global Table (PGT) . 

(a) The Task Global Table (TGT) . This 
table is used to record and save 
information needed during the 
execution of the object program. 
This information includes 
switches, addresses, and work 
areas. 

(b) The Literal Pool. This lists all 
literals used in the program, with 
duplications removed. These 
literals include those specified 
by the programmer (e.g., MOVE 
"ABC" TO DATA-NAME) and those 
generated by the compiler (e.g., 
to align decimal points in 
arithmetic computations). The 
literals are divided into two 
groups: those that are referenced 
by instructions (marked "LITERAL 
POOL") and those that are 
parameters to the display object 
time subroutine (marked "DISPLAY 
LITERALS") . 
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(Cj) The Program Global Table (PGT) , 
This table contains literals and 
the addresses of procedure-names, 
generated procedure-names, and 
procedure block locators 
referenced by Procedure Division 
instructions. 

Register assignment ; This lists the 
permanent register assigned to each 
base locator in the object program. 
The remaining base locators are given 
temporary register assignments but are 
not listed. Register assignments are 
listed when CLIST, SYM, or LISTX is 
specified, and output is not overridden 
by the same conditions as above. 

Procedure block assignments : 
Procedure block assignments are 
printed when OPT is specified. The 
procedure block assignments give the 
location within the object program for 
each block of code addressed by 
register 11. 



Object code listing . The object code 
listing is produced when the LISTX 
option is specified, unless SUPMAP is 
also specified and an E-level error is 
encountered, or unless CSYNTAX is 
specified and an E-level error is 
encountered. The actual object code 
listing contains: 



© 
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The compiler-generated card 
number. This number identifies 
the COBOL statement in the source 
deck which contains the verb that 
generates the object code found in 
column C. When VERB is specified, 
the actual verb or paragraph-name 
is listed with the generated card 
number. 



(b) The relative location, in 

hexadecimal notation, of the 
object code instruction in the 
module. 



Table 



Compiler-generated information 
about the operands of the 
generated instruction. This 
includes names and relative 
locations of literals. Table 5 
refers to information in this 
column. 



Symbols Used in the Listing and 
Glossary to Define 
Compiler-Generated Information 



Symbol 



Meaning 



© 



The actual object code instruction 
in hexadecimal notation. 



|DNM 


SOURCE DATA NAME | 


JSAV 


SAVE AREA CELL | 


JSWT 


SWITCH CELL | 


|TLY 


TALLY CELL | 


jwc 


WORKING CELL | 


ITS 


TEMPORARY STORAGE CELL | 


|VLC 


VARIABLE LENGTH CELL | 


jSBL 


SECONDARY BASE LOCATOR | 


JBL 


BASE LOCATOR | 


jBLL 


BASE LOCATOR FOR LINKAGE | 


1 


SECTION 1 


jON 


ON COUNTER | 


JPFM 


PERFORM COUNTER | 


jpsv 


PERFORM SAVE | 


|VN 


VARIABLE PROCEDURE NAME | 


JSBS 


SUBSCRIPT ADDRESS | 


JXSW 


EXHIBIT SWITCH | 


JXSA 


EXHIBIT SAVE AREA | 


JPRM 


PARAMETER | 


|PN 


SOURCE PROCEDURE NAME | 


jPBL 


Procedure Block Locator j 


jGN 


GENERATED PROCEDURE NAME | 


jDTF 


DTF ADDRESS | 


jFIB 


File Information Block j 




(for VSAN) 1 


|VNI 


VARIABLE NAME INITIALIZATION j 


|LIT 


LITERAL 1 


1TS2 


TEMPORARY STORAGE | 




(NON-ARITHMETIC) | 


|RSV 


REPORT SAVE AREA | 


JSDF 


Secondary DTF Pointer | 


|TS3 


TEMPORARY STORAGE | 




(SYNCHRONIZATION) | 


1TS4 


TEMPORARY STORAGE | 




(SYNCHRONIZATION) | 


|INX 


INDEX CELL | 


jV(BCDNAME) 


ADDRESS CONSTANT j 


jVIR 


VIRTUAL 1 


JOVF 


Overflow Cell | 


L J 


J 



^ The procedure-name number. A 
number is assigned only to 
procedure-names referred to in 
other Procedure Division 
statements. 

^ The object code instruction in the 
form that closely resembles 
assembler language. (Displacements 
are in hexadecimal notation. ) 



Stati s tics : The compiler statistics 
list the options in effect for this 
run, the number of Data Division 
statements specified, and the 
Procedure Division size. Each level 
niomber is counted as one statement in 
the Data Division. The Procedure 
Division size is approximately the 
number of verbs in the Procedure 
Division. 
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An indicator is also given here if 
dictionary spill occurred during 
compilation. If spill occurred, the 
amount of storage assigned to the 
compiler may be increased for better 
performance. Statistics are not 
listed if SYNTAX (or CSYNTAX and an 
E- level or higher error occurred) was 
in effect. 

Cross-reference dictionary ; The 
cross-reference dictionary is produced 
when the XREF or SXREF option is 
specified. It is suppressed if 
CSYNTAX is in effect and an E-level 
error is encountered. It consists of 
two parts; 



© 



in the named table, the XREF or SXREF 
for a SEARCH will reference the 
element name for the table rather than 
the table itself. LISTER could 
provide the source cross-reference 
material that might be desired. 



Diagnostic messages ; The diagnostic 
messages associated with the 
compilation are always listed. The 
format of the diagnostic message is : 



® 



® 



The cross-reference dictionary for 
data-names consists of data-names 
followed by the generated card 
number of the statement which 
defines each data-name, and the 
generated card number of state- 
ments on which the referenced 
statement begins. For MOVE 
CORRESPONDING, the data items 
actually moved are referenced. 
Report Writer data-names, with 
the exception of data-names in 
the form "-nnn", are defined 
with the generated card number 
of their respective RD's. 

The cross-reference dictionary for 
procedure- names consists of the 
procedure -names followed by the 
generated card number of the 
statement where each 
procedure-name is used as a • 
section-name or paragraph-name, 
and the generated card number of 
statements where each 
procedure-name is referenced. 



A reference will appear to a procedure 
name if there is a reference to a 
logically equivalent procedure- name; a 
reference will also appear to a 
procedure name, if, in a segmented 
program, an implied branch to a 
segment entry is made. 

If XREF is specified, the names are 
presented in the order in which they 
appear in the source program. If 
SXREF is specified, the names are 
presented alphabetically. The number 
of references appearing in the 
cross-reference dictionary for a given 
name is based upon the number of times 
the name is referenced in the code 
generated by the compiler. 

Since a SEARCH verb results in the 
examination of the individual elements 
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Compiler-generated card number. 
This is the number of a line in 
the source program related to the 
error. 

Message identification. The 
message identification for the 
DOS/VS COBOL compiler always 
begins with the symbols ILA. 

The severity level. There are 
four severity levels as follows; 

(W) Warning 

This level indicates that an 
error was made in the source 
program. However, it is not 
serious enough to interfere 
with the execution of the 
program. These warning 
messages are listed only if 
the FLAGW option is specified 
in the CBL card or chosen at 
system generation time. 

(C) Conditional 

This level indicates that an 
error was made but the 
compiler usually makes a 
corrective ass\imption. The 
statement containing the error 
is retained. Execution can be 
attempted. 

(E) Error 

This level indicates that a 
serious error was made. 
Usually the compiler makes no 
corrective assumption. The 
statement or option containing 
the error is dropped. 
Compilation is completed, but 
execution of the program 
should not be attempted. 

(D) Disaster 

This error indicates that a 
serious error was made. 
Compilation is not completed. 
Results are unpredictable. If 
this is a compiler error, the 
job will terminate via the 



^^Q 
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CANCEL macro and produce a 
dump. 

(^ The message text. The text 

identifies the condition that 
caused the error and indicates the 
action taken by the compiler. 

Since Report Writer generates a 
number of internal data items and 
procedural statements, some error 
messages may reflect internal 
names. In cases where the error 
occurs mainly in these generated 
routines, the error messages may 
indicate the card number of the RD 
entry for the report under 
consideration- In addition, there 
are errors that may indicate the 
number of the card upon which the 
statement containing the error 
ends rather than the card upon 
which the error occurs. Internal 
name formats for Report Writer are 
discussed under "Glossary" 
(heading 4, item C) . Statement 
numbers are generated when a verb 
or procedure name is encountered. 

The COBOL compile-tirae message that follows 
serves as-"an example of the format of COBOL 
compiler messages: 

CARD ERROR MESSAGE 

00105 ILA1002I-W **♦♦* SECTION HEADER 

MISSING. 
ASSUMED PRESENT. 

• The code "00105" at the left is the 
card number of the statement in which 
the error has occurred. (Some errors 
may not be discovered until information 
from various sections of the program is 
combined. For this reason, the source 
card number in the error message may 
not be exact. ) 

• ILA identifies this as a DOS/VS COBOL 
compiler message. 

• The numeral "1002" represents the 
identifying number of the message; the 
first digit of this identifier 
indicates the phase in which the error 
was detected. In this case the message 
was generated by phase 1. 

• The symbol "I" means that this is a 
message to the programmer for his 
action. 

• "W" (warning) is a level of severity in 
the error codes described in item C. 

• The five asterisks (***♦*) indicate 
words in a message that vary according 
to the program being compiled. 



The message text is usually composed of 
two sentences. The first describes the 
error; the second describes what the 
compiler has done as a result of the error. 



Note ; By specifying a PROGRAM-ID of ERRMSG 
in any source program, the user can 
generate a complete listing of compiler 
diagnostics and problem determination aids. 
(See Figure 12.) In this case, a normal 
compilation never takes place. Only a list 
of all error messages and problem 
determination information is produced. The 
link option is reset if it was in effect. 

Some messages are not given if CSYNTAX 
or SYNTAX is in effect. See "Program 
Checkout" for the list of these messages. 



1 3) FIPS Diagnostic Messages : The 

diagnostic messages associated with 
FIPS are listed separately from the 
compiler diagnostic messages, with a 
header identifying them as FIPS 
diagnostics. The format of the FIPS 
diagnostic messages is: 



® 
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Compiler-generated line number. 
This is the number of= a line in 
the source program containing a 
nonstandard element. 

Message identification. The 
message identification for FIPS 
diagnostic messages always begins 
with the symbols ILA. The 
identifying numbers of the 
messages will always be 8001, 
8002, 8003, or 8004, where: 

1 indicates an extension to a 
certain level of the FIPS 

2 indicates an extension to all 
levels of the FIPS 

3 indicates an extension to one 
or all levels of the FIPS, or 
an unusual condition; 

4 indicates that there are no 
FIPS diagnostic messages. 

The severity level. All FIPS 
diagnostic messages have a 
severity level of W (warning). 
This level indicates that 
something in the source program 
does not conform to the FIPS, but 
the compilation of the progrstn 
will not be interrupted. 

The message text. The text 
identifies the condition or 
element that does not conform to 
the FIPS. The FIPS level is also 
desianated. 
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// JOB EREORMSG User information 
// EXEC FCOBOL 

IDENTIFICATION DIVISION. 
PROGRAM-ID. ERRMSG. 
REMARKS. COMPILATION OF THIS PROGRAM WILL RESULT IN ALL COMPILER 

DIAGNOSTICS BEING PRODUCED. NO OBJECT MODULE AND NO COMPILE- 
TIME STATISTICS ARE PRODUCED. 
ENVIRONMENT DIVISION. 
DATA DIVISION. 
PROCEDURE DIVISION. 
* THE SAME RESULTS CAN BE ACHIEVED BY CHANGING THE PROGRAM-ID OF 
i * ANY PROGRAM TO 'ERHMSG'^ 
I STOP RUN. 
I 

Figure 12. A Program that Produces COBOL Compiler Diagnostics 



OBJECT MODULE 



• A map of the phase after it has been 
processed by the Linkage Editor 



The object module contains the external 
symbol dictionary, the text of the program, 
and the relocation dictionary. It is 
followed by an END statement that marks the 
end of the module. For additional 
information about the external symbol 
dictionary and the relocation dictionary, 
see the publication DOS/VS System Control 
Statements . 

An object deck is punched if the DECK 
option is specified, unless an E-level 
diagnostic message is generated. The 
object module is written on SYSLNK if the 
LINK option is specified, unless an E-level 
diagnostic message is generated. No deck 
is punched if CSYNTAX is in effect and 
E-level errors are encountered, or if 
SYNTAX is in effect. 



• Diagnostic messages 



• A listing of the linkage editor control 
statements 



• A phase which may be assigned to the 
core image library 



Any diagnostic messages associated with 
the Linkage Editor are automatically 
generated as output. The other forms of 
output may be requested by the OPTION 
control statement. All output to be listed 
is printed on the device assigned to 
SYSLST. 



LINKAGE EDITOR OUTPUT 



The output of the link edit step may 
include: 

• A printed listing of the job control 
statements 



Figure 13 is an example of a linkage 
editor output listing. It shows the job 
control statements and the phase map. The 
different types of output are numbered and 
each type to be explained is lettered. The 
text following the figure is an explanation 
of the figure. 
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// £X£C LNKEDt 



® 



JOB 


SAMPLE 






ACTION 


TAKEN MAP 


REL 


LIST 




AUTOLINK 




IJFFBZZN 


LIST 




AUTOLINK 




ILBDDSPO 


LIST 




AUTOLINK 




IJJCPDV 


LIST 




AOTOLINK 




ILBDDSSO 


LIST 




INCLUDE 


IJJCPDV 


LIST 




AUTOLINK 




ILBDIMLO 


LIST 




AUTOLINK 




ILBDMNSO 


LIST 




AUTOLINK 




ILBDSAEO 


LIST 




ENTRY 
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PHASE XFR-AD LOCOBE HICORE DSK-AD ESD TYPE LABEL 
PHASE*** 07D878 07D878 07F1FF 05F OF 4 CSECT TESTRUN 



LOADED REL-FR 

07D878 07D878 RELOCATABLE, 



CSECT IJFFBZZN 07E1C8 07E1C8 

♦ ENTRY IJFFZZZN 07E1C8 

♦ ENTRY IJFFBZZZ 07E1C8 

♦ ENTRY IJFFZZZZ 07E1C8 



♦ UNREFERENCED SYMBOLS 

® 

002 UNRESOLVED ADDRESS CONSTANTS 



CSECT 


ILBDSAEO 


07F078 


07F078 


ENTRY 


ILBDSAEl 


07F0C0 




CSECT 


ILBDMNSO 


07F070 


07F070 


CSECT 


ILBDIMLO 


07F018 


07F018 


CSECT 


ILBDDSPO 


07E578 


07E578 


ENTRY 


ILBDDSPl 


07E978 




CSECT 


ILBDDSSO 


07ECF0 


07ECF0 


ENTRY 


ILBDDSSl 


07EF50 




ENTRY 


ILBDDSS2 


07EFt8 




ENTRY 


ILBDDSS3 


07F008 




ENTRY 


ILBDDSSU 


07ED16 




ENTRY 


ILBDDSS5 


07EDC2 




ENTRY 


ILBDDSS6 


07EE22 




ENTRY 


ILBDDSS7 


07EDEC 




ENTRY 


ILBDDSS8 


07ED46 




CSECT 


IJJCPDV 


07EAA8 


07EAfl8 


ENTRY 


IJJCPDVl 


07EAA8 




* ENTRY 


IJJCPDV2 


07EAA8 




WXTRN 


STXITPSW 






WXTRN 


ILBDDBG2 
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Figure 13. Linkage Editor Output 
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(^ The -jou control statements . These 

statements are listed because the LOG 
option is specified- 

(2) Disk linkage editor diagnostic message 
of input . The ACTION statement is not 
required. If the MAP option is 
specified, SYSLST must be assigned. 
If the statement is not used and 
SYSLST is assigned, MAP is assumed and 
a storage map and any error diagnostic 
messages are considered output on 
.c;vc;t.«t_ 



Comments on the Phase Map 



The severity of linkage editor 
diagnostic messages may affect the 
production of the phase map. Since various 
processing options affect the structure of 
the phase, the text of the phase map will 
sometimes provide additional information. 
For example, the phase may contain an 
overlay structure. In this case, a map 
will be listed for each segment in the 
overlay structure. 






© 



Map of virtual storage . A phase map 
is printed when MAP is specified (or 
assumed) during linkage editor 
processing. The following information 
is contained in the storage map: 



The name of each phase. This is 
the name specified in the phase 
statement. 

The transfer address of each 
phase. 

The lowest virtual storage 
location of each phase. 

The highest virtual storage 
location of each phase - 

The hexadecimal disk address where 
the phase begins in the core image 
library. 

The names of all CSECT's belonging 
to a phase- 
All defined entry points within a 
CSECT. If an entry point is not 
referenced, it is flagged with an 
asterisk (*). 

The address where each CSECT is 
loaded. 

The relocation factor of each 

CSECT. 

The number of unresolved weak 
external references. This 
indication need not concern the 
programmer. An unresolved weak 
external reference does not cause 
the Linkage Editor to use the 
automatic library call mechanism. 
Instead, the reference is left 
unresolved, and the load module is 
marked as executable. The number 
of unresolved address constants 
will not necessarily be the same 
as the number of unreferenced 
symbols listed in the Linkage 
Editor output. 



® 
© 



© 
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Linkage Editor Messages 



The Linkage Editor may generate 
informative or diagnostic messages. A 
complete list of these messages is included 
in the publication DOS/VS System. Control 
Statements - 



DOS ANS COBOL Unresolved External 
References 



When the Linkage Editor encounters a 
weak external reference (WXTRN) , 
autolinking is suppressed and the V-type 
address constant is either resolved from 
those modules included into the load module 
or it remains unresolved. Unresolved 
WXTRNs will not cause the Linkage Editor to 
cancel the link step if ACTION CANCEL is in 
effect. 



The DOS/VS COBOL object time subroutine 
library utilizes WXTRNs not only as address 
constants but also as switches to determine 
at object time whether certain options are 
in effect. It is a very convenient feature 
which can lead to tight and efficient code. 

Unresolved WXTRNs are normally 
intentional but unresolved EXTRNs are 
normally unintentional and an error. 

Any of the following unresolved WXTRNs 
may appear when link editing an object 
module produced by an ANS COBOL compiler: 



^ffl 



STXITPSW 

ILBDDBG2 

ILBDADRl 

ILBDDBGO 

SORTEP 

ILBDSTNO 

ILBDFLWO 



ILBEFLW2 
ILBDSRTO 
ILBDRELO 
ILBDTEFO 
ILBDDSSl 
ILBEDSS3 
ILBDVOCl 



ILBDMRGO 
ILBDFLW3 
ILEDTCOO 
ILBDTCOl 
ILBDDEG7 
ILBDDBG8 
ILBDTC3 
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COBOL E X ECUT ION OUTPUT 

The output generated by program 
execution (in addition to data written on 
output files) may include: 

• Data displayed on the console or on the 
printer 

• Diagnostic messages to the programmer 

• Messages to the operator 

• System informative messages 

• SYMDMP, STATE, FLOW, and/or COUNT 
output 

• System diagnostic messages 

• A system dump 

Appendix I contains the full list of 
execution time diagnostic messages. 



is discussed in the chapter entitled 
"Symbolic Debugging Features". 

COUNT output is generated upon normal or 
abnormal termination of the program. 
Output from this feature is described in 
the chapter "Execution Statistics". 

Figure 14 is an example of output from 
the execution job step. The following text 
is an explanation of the illustration. 

(^ Job control statements. These 

statements are listed because the LOG 
option is specified. 

(2) Program output o n printer . The 

results of execution of the EXHIBIT 
NAMED statement appear on the program 
listing. 

\3) Console output . Data is printed on 

the console output unit as a result of 
the execution of DISPLAY UPON CONSOLE. 



A dump and system diagnostic messages 
are generated automatically during program 
execution only if the program contains 
errors that cause abnormal termination. 

SYMDMP output is generated upon request, 
or upon abnormal termination. STATE and 
FLOW output are generated upon abnormal 
termination. The output of these features 



OPERATOR MESSAGES 



The COBOL phase may issue operator 
messages. In the message, XX denotes a 
system-generated 2-character numeric field 
that is used to identify the program 
issuing the message. 



// ASSGN : 


3YS008,X' 


483* 


\ 


// EXEC 










S 


W0RK-R3C0RD 


:=: 


A 


0001 


NYC 


z 


WORK-RECORD 


= 


B 


0002 


NYC 


1 


WORK-RECORD 


= 


C 


0003 


NYC 


2 


WORK-RECORD 


= 


D 


OOOtf 


NYC 


3 


WORK-RECORD 


= 


E 


000 5 


NYC 


4 


WCRK-RECORD 


= 


F 


0006 


NYC 


Z 


WORK-RSCORD 


= 


G 


0007 


NYC 


1 


WORK-RECORD 


= 


H 


0008 


NYC 


2 


WORK-RECORD 


= 


I 


0009 


NYC 


3 


WORK-RECORD 


= 


J 


0010 


NYC 


4 


WORK-RECORD 


= 


K 


0011 


NYC 


Z 


WCRK-RECORD 


= 


L 


0012 


NYC 


1 


WORK-RECORD 


= 


M 


0013 


NYC 


2 


WCRK-RECORD 


= 


N 


0014 


NYC 


3 


WORK-RECORD 


= 





0015 


NYC 


4 


WCRK-RECORD 


= 


P 


0016 


NYC 


Z 


WORK-RECORD 


= 


Q 


0017 


NYC 


1 


WORK-RECORD 


= 


R 


0018 


NYC 


2 


WORK-RECORD 


= 


S 


0019 


NYC 


3 


WCRK-RECORD 


= 


T 


0020 


NYC 


4 


WORK-RECORD 


= 


U 


0021 


NYC 


Z 


WCRK-RECORD 


= 


V 


0022 


NYC 


1 


WORK-RECORD 


= 


w 


0023 


NYC 


2 


WORK-RECORD 


- 


X 


0024 


NYC 


3 


WORK-RECORD 


= 


Y 


0025 


NYC 


4 


WCRK-RECORD 


= 


Z 


0026 


NYC 


Z 


Figure 14. 




Or 


itput 


frc 


)m 
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BG 




BG A 0001 NYC \ 




BG B 0002 NYC 1 




BG C 0003 NYC 2 




BG D 0004 NYC 3 




BG E 0005 NYC 4 




BG F 0006 NYC 




BG G 0007 NYC 1 




BG H 0008 NYC 2 




BG I 0009 NYC 3 




BG J 0010 NYC 4 


1 


BG K 0011 NYC 




BG L 0012 NYC 1 


i 


BG M CG13 NYC 2 
BG N 0014 NYC 3 


)© 


BG 0015 NYC 4 i 


( 


BG P 0016 NYC 




BG Q 0017 NYC 1 




BG R 0018 NYC 2 




BG S 0019 NYC 3 




3G T 0020 NYC 4 




BG U 0021 NYC 




BG V 0022 NYC 1 




BG W 0023 NYC 2 




BG X 00 24 NYC 3 




BG Y 0025 NYC 4 / 




BG Z 0026 NYC / 




BG EOd SAMPLE / 




00.56. 19, DURATION 


00.03.42 



72 



STOP Statement 



SYSTEM OUTPUT 



The following message is generated by 
the STOP statement with the literal option: 

XX CllOA STOP "literal" 

Explanation : This message is issued at the 
programmer's discretion to indicate 
possible alternative action to be taken by 
the operator. 

Operator Response : Follows the 
instructions given both by the message and 
on the job request form supplied by the 
programmer. If the job is to be resumed, 
hit the end/enter key. 



ACCEPT Statement 



The following message is generated by an 
ACCEPT statement with the FROM CONSOLE 
option: 

XX ClllA "AWAITING REPLY" 



Explanation : This message is issued by the 
object program when operator intervention 
is required- 

Operator Response ; Enter the reply and hit 
the end/enter key- (The contents of the 
text field should be supplied by the 
programmer on the job request form. ) 
Alphabetic characters may be entered lower 
case. 



Informative and diagnostic messages may 
appear in the listing during the execution 
of the object program. 



Each of these messages contains an 
identification code in the first column of 
the message to indicate the portion of the 
operating system that generated the 
message. Table 6 lists these codes, 
together with identification for each. 



Table 6. System Message Identification 
Codes 



r T" 

1 Code j 



Identification 



J- 


-+- 










4 


1 


1 


An on-line con 


sole 


message froin | 




] 




the Supervisor 






1 








1 




1 








1 


i 1 


1 

1 

1 


A 


message from 
Processor 


the 


Job Control | 




i 








1 


1 2 


1 
1 


A 


message from 


the 


Linkage Editor | 
J 




J 








1 


1 3 


1 

1 


A 


message from 


the 


Librarian j 




1 








1 


i 4 


1 


A 


message from 


LIOCS 1 




1 








1 




i 








"J 


1 7 


1 
1 


A 


m.essage from 


the 


Sort program j 




i 








1 


1 c 


1 


A 


message from 


COBOL object-time \ 




1 




subroutines 




1 


1 










J 
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CALLING AND CALLED PROGRAMS 



This chapter describes the accepted 
linkage conventions for calling and called 
programs and discusses linkage methods when 
using an assembler language program. In 
addition, this chapter contains a 
description of the overlay facility which 
enables different called programs to occupy 
the same area in virtual storage at 
different times. It also contains a 
suggested assembler language program to be 
used in conjunction with the overlay 
feature. 

A COBOL source program that passes 
control to another program is a calling 
program . The program that receives control 
from the calling program is referred to as 
a called program . Both programs must be 
compiled (or assembled) in separate job 
steps, but the resulting object modules 
must be link edited together in the same 
phase. 

A called program can also be a calling 
program; that is, a called program can, in 
turn, call another program. In Figure 15 
for instance, program A calls program B; 
program B calls program C. Therefore: 

1. A is considered a calling program by B 

2. B is considered a called program by A 

3. B is considered a calling program by C 

4. C is considered a called program by B 



Compiler-generated switches, e.g., ON 
and ALTER, are not reinitialized upon each 
entrance to the called program, that is, 
the program is in its last executed state. 

Note: It is necessary for an American 
National Standard COBOL program to know 
whether it is the main or the called 
program. For this reason, any non-American 
National Standard COBOL program calling an 
American National Standard program must 
first call the subroutine ILBDSETO. The' 
function of this subroutine is to set a 
switch to X^FF* in subroutine ILBDMNSO, 
which is the indication to the COBOL 
program that it is a called program. 
Standard linkage conventions should be 
observed when calling ILBDSETO j there are 
no parameters to be passed. 



LINKAGE 



Whenever a program calls another 
program, linkage must be established 
between the two. The calling program must 
state the entry point of the called program 
and must specify any arguments to be 
passed. The called program must have an 
entry point and must be able to accept the 
arguments. Further, the called program 
must establish the linkage for the return 
of control to the calling program. 



B 



I Calling 
I program 
I of B 



I Called 
I program 
I of A 



->l 



1 Calling 
I program 
I of C 



[Called 
I program 
I of B 



->l 



Figure 15. Calling and Called Programs 



By convention, a called program may call 
to an entry point in any other program, 
except one on a higher level in the "path" 
of that program. That is, A may call to an 
entry point in B or C, and B may call C; 
however, C should not call A or B. 
Instead, C transfers control only to B by 
issuing the EXIT PROGRAM or GOBACK 
statements in COBOL (or its equivalent in 
another language) . B then returns to A. 



LINKAGE IN A CALLING PROGRAM 



A calling COBOL program must contain the 
following statement at the point where 
another program is to be called : 



I CALL literal-1 F USING identifier-1 
I [ identif ier-2]. . . ] 



literal-1 

is the name specified as the 
program-name in the PROGRAM-ID 
paragraph of the called program, or 
the name of the entry point in the 
called program. When the called 
program is to be entered at the 
beginning of the Procedure Division, 
literal-1 is the name of the program 
being called. When the called program 
is to be entered at some point other 
than the beginning of the Procedure 
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Division, literal-1 should not be the 
same as the name specified in the 
PROGHAM-ID paragraph of the called 
program. Since the program-name in 
the PHOGRAM-ID paragraph produces an 
external reference defining an entry 
point, this entry point name would not 
be uniguely defined as an external 
reference. 

If the first character of PROGRAM-ID 
is numeric, the correspondence 
algorithm is as follows: 

becomes J 
1-9 become A -I 

Since the system does not include the 
hyphen as an allowable character, the 
hyphen is converted to zero if it 
appears as the second through eighth 
character of the name. 

identifier-1 [ identif ier-2 ]. . . 

are the arguments being passed to the 
called program. Each identifier 
represents a data item defined in the 
File, Working-Storage, or Linkage 
Section of the calling program and 
should contain a level number 01 or 
77. When passing identifiers from the 
File Section, the file should be open 
before the CALL statement is executed. 
If the called program is an assembler 
language program, the arguments may 
represent file-names and procedure- 
names in addition to data-names. If 
no arguments are to be passed, the 
USING option is omitted. 



LINKAGE IN A CALLED PROGRAM 



M 
I 



I ENTRY literal-1 [USING identifier-1 I 
I [ identif ier-2 ]... ] | 

I I 

literal-1 

is the name of the entry point in 
the called program . It is the 
same name that appears in the 
CALL statement of the program 
that calls this program. 

literal-1 must not be the name of 
any other entry point or 
program-name in the run unit. 

identifier-1 [ identif ier-2 ]. . . ] 

are the data items representing 
parameters. They correspond to 
the arguments of the CALL 
statement of the calling program. 
Each data item in this parameter 
list must be defined in the 
Linkage Section of the called 
program and must contain a level 
number of 01 or 77. 

2. Either of the following statements 
must be inserted where control is to 
be returned to the calling program: 

I 1 

I EXIT PROGRAM. | 

I , 

I GOBACK. I 



Both the EXIT PROGRAM and GOBACK 
statements cause the restoration of 
the necessary registers, and return 
control to the point in the calling 
program immediately following the 
calling sequence. 



A called COBOL program must contain two 
sets of statements: 



One of the following statements must 
appear at the point where the program 
is entered. 

If the called program is entered at 
the first instruction in the Procedure 
Division and arguments are passed by 
the calling program: 



I PROCEDURE DIVISION [USING 

I identifier-1 [ identif ier-2 ], 



If the entry point of the called 
program is not the first statement of 
the Procedure Division: 



ENTRY POINTS 



Each time an entry point is specified in 
a called program, an external-name is 
defined. An external-name is a name that 
can be referenced by another program that 
has been separately compiled or assembled. 
Each time an entry name is specified in a 
calling program, an external reference is 
defined. An external reference is a symbol 
that is defined as an external-name in 
another separately compiled or assembled 
program. The Linkage Editor resolves 
external-names and external references, and 
combines calling and called programs into a 
format suitable for execution together, 
i.e., as a single phase. 



{ 
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Note ; Several different entry points may 
be defined in one COBOL source module. 
Different CALL statements in any module of 
the phase may specify the same entry point, 
but each definition of an entry point must 
be unique in the same phase. 



CORRESPONDENCE OF ARGUMENTS AND PARAHETERS 



SUBPRGD. Also assume that the module sizes 
for the main program and subprograms are: 



The number of identifie 
argument list of the calli 
be *the same as the number 
the parameter list of the 
If the number of identifie 
argument list of the calli 
greater than the number of 
the parameter list of the 
only those specified in th 
of the called program may 
the called program. There 
correspondence. The corre 
positional and not by name 
must not appear more than 
USING clause. 



rs in the 

ng program should 

of identifiers in 

called program. 

rs in the 

ng program is 

identifiers in 
called" program, 
e parameter list 
be referred to by 

is a one-for-one 
spondence is 

An identifier 
once in the same 



Only the address of an argument is 
passed. Consequently, both the identifier 
that is an argument and the identifier that 
is the corresponding parameter refer to the 
same location in storage. The pair of 
identifiers need not be identical, but the 
data descriptions must be equivalent. For 
example, if an argument is a level-77 
data-name representing a 30-character 
string, its corresponding parameter could 
also be a level-77 data-name representing a 
character string of length 30, or the 
parameter could be a level -01 data item 
with subordinate items representing 
character strings whose combined length is 
30. 

Although all parameters in the ENTRY 
statement must be described with level 
numbers 01 or 77, there is no such 
restriction made for arguments in the CALL 
statement. An argument may be a qualified 
name or a subscripted name. When a group 
item with a level number other than 01 is 
specified as an argument, proper boundary 
word alignment is required if subordinate 
items are described as COMPUTATIONAL, 
COHPUTATIONAL-1, or COMPUTATIONAL-2 . If 
the argument corresponds to an 01 -level 
parameter, doubleword alignment is 
required. 



LINK EDITING WITHOUT OVERLAY 



P rogra m 
COBMAIN 
SOBPRGA 
SUBPRGB 
SUBPRGC 
SUBPRGD 



Module Size 
(in bytes ) 
20,000 

4,000 

5,000 

6,000 

3,000 



Through the linkage mechanism, all 
called programs plus COBMAIN must be link 
edited together to form one module of 
38,000 bytes. Therefore, COBMAIN would 
require 38,000 bytes of storage in order to 
be executed. No overlay structure need be 
specified at link edit time if 38,000 bytes 
of virtual storage are available. 



The following is an example of the job 
control statements needed to link edit 
these calling and called programs without 
specifying an overlay structure . The 
source decks for COBMAIN and SUEPRGA are 
included in the job deck, whereas SUBPRGB, 
SUBPRGC, and SUBPRGD are in the relocatable 
library. 



// 
// 



/* 



/* 

// 
// 



/* 



JOB NOVERLAY 

OPTION LINK, LIST, DUMP 

ACTION MAP 

PHASE EXAMP1,* 

INCLUDE 

{object module COBMAIN} 

INCLUDE SUBPRGB 
INCLUDE SUBPRGC 
INCLUDE SUBPRGD 
INCLUDE 

{object module SUBPRGA) 

ENTRY 

EXEC LNKEDT 

EXEC 

{data for program} 




Assume that a COBOL main program 
(COBMAIN) , at one or more points in its 
logic executes CALL statements to COBOL 
programs SUBPRGA, SUBPRGB, SUBPRGC, and 



Figure 16 is an example of the data flow 
logic of this call structure where all the 
programs fit into virtual storage. 
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SYSIPT 



Main Program 




SUBPRG B — 1 



SUBPRG C 



\ 



SUBPRG D 



Execute 
LNKEDT 



SUBPRG A 



Job Control 



Linkage 
Editor 





1 



Storage 
Layout 



Figure 16. Example of Data Flow Logic in a 
Call Structure 



Note : For the example given, it is assumed 
that SYSLNK is a standard assignment. The 
flow diagram illustrates how the various 
program segments are link edited into 
storage in a sequential arrangement. 



ASSEMBLER LANGUAGE SUBPROGRAMS 



A main program written in COBOL can call 
programs written in other languages that 
use the same linkage conventions. Whenever 
a COBOL program calls an assembler language 
program, certain conventions and techniques 
must be used. 

There are three basic ways to use 
assembler-written called programs with a 
main program written in COBOL: 

1 . A COBOL main program or called program 
calling an assembler-writtem prograsi. 

2. An assembler-written program calling a 
COBOL program. 

3. An assembler-written program calling 
another assembler-written program. 



From these combinations, more 
complicated structures can be formed. 

In a COBOL program, the expansions of 
the CALL and GOBACK or EXIT PROGRAM 
statements provide the save and return 
coding that is necessary to establish 
linkage between the calling and called 
programs in accordance with the linkage 
conventions of the system. Assembler 
language programs must be prepared in 
accordance with the same linkage 
conventions. These conventions include: 

1. Using the proper registers to 
establish linkage. 

2. Reserving, in the calling program, a 
storage area for items contained in 
the argument list. This storage area 
can be referenced by the called 
program. 

3. Reserving, in the calling program, a 
save area in which the contents of the 
registers can be saved. 



REGISTER USE 



The Disk Operating System has assigned 
functions to certain registers used in 
linkages. Table 7 shows the conventions 
for using general registers as linkage 
registers. The calling program must load 
the address of the return point into 
register 14, and it must load the address 
of the entry point of the called program 
into register 15. 

Table 7. Conventional Use of Linkage 
Registers 



1 "■ — ■■■ ■!■''■■ T"- — - ■ — — , 

|Reg. I Reg. | | 
|No. IName | Function | 
III 1 


1 1 1 Argument! Address of the argument | 
1 (list 1 list passed to the called | 
1 1 register! program. | 
til ■ 


!13 ! Save f Address of the area re- j 
1 !area | served by the calling pro-| 
1 1 register! gram in which the contents! 
! 1 ! of certain registers are | 
! ! 1 stored by the called | 
! 1 ! program. ! 
Ill 1 


! 14 ! Return ! Address of the location in! 
! 1 register! the calling program to | 
! ! 1 which control is returned I 
1 i 1 after execution of the j 
1 1 ! called program. | 
ill * 


1 1 1 -.,,_., — 1 
1 15 1 Entry | Address of the entry point! 
1 1 point 1 in the called program. | 
1 {register! I 
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SAVE AREft 



ARGUMENT LIST 



A calling assembler language program 
must reserve a save area of 18 words, 
beginning on a fullword boundary, to be 
used by the called program for saving 
registers; it must load the address of this 
area into register 13. Table 8 shows the 
layout of the save area and the contents of 
tfach word. 



A called COBOL program does not save 
floating-point registers. The programmer 
is responsible for saving and restoring the 
contents of these registers in the calling 
program. 



Table 8. Save Area Layout and Word 
Contents 



Ji li £ A 

(word 1) 



AREA+U 
(word 



AREA+8 
(word 



AREA+r 
(word 



2) 



3) 



**) 



AREA+16 
(word 15) 

AREA+20 
(word 6) 

AREA+24 
(word 7) 



AREA+68 
(word 18) 



This word is a part of the 
standard linkage convention 
established under the DOS/VS 
System. The word must be 
reserved for proper 
addressing of the subsequent 
entries. However, an 
assembler subprogram may use 
the word for any desired 
purpose. 



The address of the previous 
save area, that is, the save 
area of the subprogram that 
called this one. 



The address of the next save 
area, that is, the save area 
of the subprogram to which 
this subprogram refers. 



The contents of register 14, 
that is, the return address. 



The contents of register 15, 
that is, the entry address. 



The contents or register 0. 



The contents of register 1, 



The contents of register 12. 



The argument list is a group of 
contiguous full words, beginning on a 
fullword boundary, each of which is an 
address of a data item to be passed to the 
called program. If the program is to pass 
arguments, an argument list must be 
prepared and its address loaded into 
register 1. The high-order bit of the last 
argument, by convention, is set to 1 to 
indicate the end of the list. 



Any assembler-written program must be 
coded with a detailed knowledge of the data 
formats of the arguments being passed. 
Host coding errors occur because of the 
data format discrepancies of the arguments. 

If one programmer writes both the 
calling program and the called program, the 
data format of the arguments should not 
present a problem when passed as 
parameters. However, when the programs are 
written by different programmers, the data 
format specifications for the arguments 
must be clearly defined for the programmer. 



The linkage conventions used by an 
assembler program that calls another 
program are illustrated in Figure 16. The 
linkage should include: 

1. The calling sequence. 

2. The save anu return routines. 

3. The out-of-line parameter list. (An 
in-line parameter list may be used.) 

4. A save area on a fullword boundary. 
FILE-NAME AND PFOCEDORE-NAME ARGUMENTS 



A callina COBOL program that calls an 
assembler-language program can pass 
file-names and procedure-names, in addition 
to data-names, as identifiers. In the 
actual identifier-list that the compiler 
generates, the procedure-name is passed as 
the address of the procedure. For a file, 
the address of the DTF is passed, and the 
user must ensure that the file is already 
open. A VSAM file-name may not be passed. 

Care must be taken when using these 
options. The user must be thoroughly 
familiar with the generated coding for each 
option and statement, as well as the 
structure of the object program . 



i 
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deckname STAPT 





* 




ENTRY 


namei 


EXTBN 


name2 


USING 


namei , 15 


* SAVE ROUTINE 




name^ STM 


14,ri,12 


* 




* 




* 





LR r3,15 
DROP 15 
USING namei, r3 



LR 

LA 

ST 



r2,13 

13, AREA 
13,8{r2) 



* 






* 






* 


ST 


r2,U{13) 


* 
* 








BC 


15,prob^ 


AREA 


DS 


18F 


probi 


{User- 


-written progra 




L 


15,VC0N 




BALR 


14,15 


* CALLING SEQUENCE 




LA 


1,ARGLST 




L 


15,ADC0N 




BALR 


14,15 




{Remainder of user-w 


* RETURN 


ROUTINE 


^ 


L 


13,4(13) 




Lfl 


2, r,, 28(13) 


» 








L 


14,12(13) 



MVI 



12(13) ,X»FF' 



BCR 
VCON DC 
ADCON DC 
* PARAMETER LIST 
ARGLST DC AL4 (arg J 

DC AL4(arg2) 



15,14 

V{ILBDSETO) 
A (namej) 



INITIATES PROGRAM ASSEMBLAGE AT FIRST 
AVAILABLE LOCATION. ENTRY POINT TO THE 
PROGRAM. 



THE CONTENTS OF REGISTERS 14, 15, AND 

THROUGH ri ARE STORED IN THE SAVE 

AREA OF THE CALLING PROGRAM (PREVIOUS 

SAVE AREA) . Ti IS ANY NUMBER FROM THROUGH 12, 



WHERE ra AND V2 HAVE BEEN SAVED 

LOADS REGISTER 13, WHICH POINTS TO THE 

SAVE AREA OF THE CALLING PROGRAM, INTO 

ANY GENERAL REGISTER, ra , EXCEPT AND 13, 

LOADS THE ADDRESS OF THIS PROGRAM'S 

SAVE AREA INTO REGISTER 13. 

STORES THE ADDRESS OF THIS PROGRAM'S SAVE 

AREA INTO WORD 3 OF THE SAVE AREA OF THE 

CALLING PROGRAM. 

STORES THE ADDRESS OF TEE PREVIOUS SAVE 

AREA (I.E., THE SAME AREA OF THE CALLING 

PROGRAM) INTO WORD 2 OF THIS PROGRAM'S 

SAVE AREA. 

RESERVES 18 WORDS FOR TEE SAVE AREA 
THIS IS LAST STATEMENT OF SAVE ROUTINE, 
m statements} 
INDICATE COBOL PROGRAM IS 
A SUBPROGRAM 



ritten program statements) 

LOADS THE ADDRESS OF THE PREVIOUS SAVE 

AREA BACK INTO REGISTER 13. 

THE CONTENTS OF REGISTER 2 THROUGH r^ ARE 

RESTORED FROM THE PREVIOUS SAVE AREA. 

LOADS THE RETURN ADDRESS, WHICH IS IN 

WORD 4 OF THE CALLING PROGRAM'S SAVE AREA, 

INTO REGISTER 14. 

SETS FLAG FF IN THE SAVE AREA OF THE 

CALLING PROGRAM TO INDICATE THAT CONTROL 

HAS RETURNED TO THE CALLING PROGRAM. 

LAST STATEMENT IN RETURN ROUTINE 

CONTAINS THE ADDRESS OF SUBPROGRAM names. 

FIRST STATEMENT IN PARAMETER AREA SETUP 



Fi atiTo 17 



DC 
DC 



X'80» 
AL3 (arg^) 



Sain.'~'le Linkaoe Routin' 



FIRST BYTE OF LAST ARGUMENT SETS BIT TO 
LAST STATEMENT IN PARAMETER AREA SETUP 
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OVERLAYS 



ADCON 



RETURN 



DC 


A (probi) 


LA 


lU, RETURN 


L 


15,ADC0N 


CHOP 


2,4 


BALE 


ni5 


DC 


AL4 (argO 


DC 


ALUCarg^) 



DC 
DC 
EOU 



X'80» 
AL3 (argn) 
* 



Figure 18. Sample In-line Parameter List 
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In-Line Parameter List 



The following is a diagram of the basic 
form of a program to be overlaid: 



The assembler programmer may establish 
an in-line parameter list instead of an 
out-of-line list. In this case, he may 
substitute the calling sequence and 
parameter list illustrated in Figure 18 for 
that shown in Figure 17. 



LOWEST LEVEL PROGRAM 



If an assembler called program does not 
call any other program (i.e., if it is at 
the lowest level) , the programmer should 
omit the save routine, calling sequence, 
and parameter list shown in Figure 17. If 
the assembler called program uses any 
registers, it must save them. Figure 19 
illustrates the appropriate linkage 
conventions used by an assembler program at 
the lowest level. 



deckname START 

ENTRY name 



USING 
STH 



*,15 

14, r,, 12(13) 



User-written program statements 



LH 


2, r,, 28(13) 


MVI 


12(13) ,X'PF» 


BCR 


15,14 



Note : If registers 13 and/or 14 are used 

in the called subprogram, their contents 

|shr Id be saved and restored by the 

I called subprogram. 

I 

Figure 19. Sample Linkage Routines Used 

with a Lowest Level Subprogram 



ROOT PHASE 



SUBA 



SUBB 



The root phase consists of the COBOL 
main program and an assembler language 
subroutine which handles the overlay 
structures. SUBA and SUBB are the called 
programs that are to be overlaid in 
storage. 

In using the overlay technique, the 
programmer specifies to the Linkage Editor 
which programs are to overlay each other. 
These programs are processed by the Linkage 
Editor so they can be placed automatically 
in storage for execution when called by the 
main program. The resulting output of the 
Linkage Editor is called an overlay 
structure. 



SP ECIAL CONSIDERATIONS WHEN USI NG OVER LAY 
STRUCTURES 



There are three areas of special concern 
to the proQrammer who decides to use the 
overlay feature. These problems concern 
the use of the assembler language 
subroutine, proper link editing, and job 
control statements. 






Callina and Called Programs 



ASSEMBLER LANGUAGE SUBROUTINE FOR 
ACCOMPLISHING OVERLAY 



The CALL statement is used for "direct" 
linkage; that is, the assistance of the 
Supervisor is not required (as it is when 
loading or fetching a phase) . There are no 
COBOL statements that will generate the 
equivalent of the LOAD or FETCH assembler 
macro instructions. For this reason, one 
must call an assembler program to effect an 
overlay of a COBOL program. This routine 
must be link edited as part of either a 
root phase or permanently resident phase. 

The sample overlay subroutine shown in 
Figure 20 is governed by the following 
restrictions: 

1. The example is a suggested technique, 
and is not the only technique. 



It can be used for assembler overlays 
if the programmer has a desired entry 
point in his END card and the first 
statement at that entry point is »STM 
14,12,12(13) '. 



This subroutine can be used for a 
COBOL program which contains an ENTRY 
statement immediately following the 
Procedure Division header. It will 
not work with a COBOL subprogram 
compiled with a Procedure Division 
USING statement or for entry points in 
a COBOL subprogram which appear 
anywhere other than as the first 
instruction of the Procedure Division. 
A suggested technique for diverse 
entry points is a table look-up using 
V-type constants. 



STHNT 

0001 
0002 
0003 
0004 
0005 
0006 
0007 
0008 
0009 
0010 
0011 
0012 
0013 
0014 
0015 
0016 
0017 
0018 
0019 
0020 
0021 
0022 
0023 
0024 
0025 
0026 
0027 
0028 
0029 
0030 
0031 
0032 
0033 
0034 
0035 
0036 
0037 
0038 
0039 



SOURCE STATEMENT 

OVERLAY START 

ENTRY OVRLAY 

* AT ENTRY TIME 

* R1=P0INTER TO ADCON LIST OF USING ARGUMENTS 

* FIRST ARGUMENT IS PHASE OR SUBROUTINE NAME 

* MUST BE 8 BYTES 

* R13=ADDRESS OF SAVE AREA 

* R14=RETUEN POINT OF CALLING PROGRAM 

* R15=ENTRY POINT OF OVFRLAY PROGRAM 

* AT EXIT 

* R1=P0INTER TO SECOND ARGUMENT OF ADCON LIST 

* OF USING ARGUMENTS 

* R14=RETURN POINT OF CALLING PROGRAM — NOT THIS PROG 

* R15=ENTRY POINT OF PHASE OR SUBPROGRAM 
* 



USING *,15 

OVRLAY STM 0,1, SAVE 

L 1,0(1) 

CLC CORSUB,0(1) 

BE SUBIN 

MVC C0RSUB(8) ,0 (1) 

SR 0,0 

SVC 4 

SEARCH1 LA 1,4(1) 

CLC (3,1) ,=C'C0B' 

BNE SEARCH1 

S 1 , =F • 8 » 

L 1,0(1) 

LA 1,8(1) 

ST 1,ASUB 

SUBIN LM 0,1, SAVE 

LA 1,4(1) 

L 15,ASUB 

BR 15 



SAVE WORK REGS 

POINT R1 TO PHASE NAME 

IN CORE? 

YES, BR 

SET CURRENT PHASE 

LOAD PHASE 

STEP SEARCH POINT 

END OF INIT1? 

NO, LOOP 

POINT TO "START" ADCON 

LOAD "START" 

INCREMENT TO "ENTRY" 

SAVE ENTRY ADDRESS 

RELOAD WORK REGS 

POINT TO PARAMETERS 

BRANCH TO ENTRY POINT 



CORSUB 

ASUB 
SAVE 



DC 8X«FF' 

DS F 

DS 2F 
END 



Figure 20. Example of an Assembler Language Subroutine for Accomplishing Overlay 
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Note : Care should be taken with the 
techniques used in statements 0019 and 
0020. Only when the COBOL program is 
loaded are altered GO TO statements 
reinitialized. A better technique would be 
to load the called programs each time they 
are required. 

The examples given in Figures 20, 21, and 
22 require that all overlay modules be linked 
together. To permit linkage to and return 
from modules, compiled and link edited 
separately, the following changes to 
Figure 20 are necessary: 

Replace lines 25 through 28 



CLC COBCON,20(1) END OF INIT? 

BNE SEARCHl NO, LOOP 

LR 0,1 SAVE ADDR ADCON INITl 

L 1,0(1) GET INITl ADDR 

MVC N0P+3(1) ,139 (1) GET DISP OF VIRT CELL 

LR 1,0 RESTORE ADDR OF ADCON INITl 

L 1,4(1) GET ADDR OF PGT 

NOP L 1,0(1) LOAD ADDR OF ILBDMNSO 

MVI 0(1),X'FF' SET 'CALLED PROGR' FLAG 

LR 1,0 RESTORE ADDR OF ADCON INITl 

L 1,12(1) LOAD 'START' ADDRESS 



Also, to achieve maximum overlay, the phase 
names for the called programs should be 
different from the names of the called 
programs specified in the PROGRAH-ID 
paragraphs. 



Figure 21 is a flow diagram of the 
overlay logic. The PHASE cards indicate 
the beginning address of each phase. The 
phases OVERLAYC and OVEELAYD will have the 
same beginning address as OVERLAYB. The 
sequence of events is: 

1. The main program calls the overlay 
routine. 

2. The overlay routine fetches the 
particular COBOL subprogram and places 
it in the overlay area. 

3. The overlay routine transfers control 
to the first instruction of the called 
program. 

4. The called program returns to the 
COBOL calling program ( not to the 
assembler language overlay routine) . 



Insert after line 38 

COBCON DC CL3'C0B' 

LINK EDITING HITE OVERLAY 



If OVERLAYB were known to be in storage, 
the CALL statement would be: 



I CALL "OVERLAYB" USING PARAH-1, PARAW-2.| 
I I 



j-ii a. j.a.iiAaycr CU.J.I.V/J. jOjj oXt?^, UiiB 

programmer specifies the overlay points in 
a program by using PHASE statements. In 
the Working-Storage Section, a level-01 or 
level-77 constant must be created for each 
phase to be called at execution time. 
These constants have a PICTURE of X (8) and 
a VALUE clause containing the same name as 
that appearing on the PHASE card for that 
segment in the link edit run. 

In addition, each argument to be passed 
to the called program must have an entry in 
the Linkage Section. Remember, also, that 
the ENTRY statement should not refer to the 
program-name. (Use of the program-name 
will result in incorrect execution.) 

When more than one subprogram in the 
overlay structure requires the same COBOL 
subroutine, the // EXEC LNKEDT statement 
must be preceded by INCLUDE cards for each 
of these subroutines. The names of these 
subroutines can be determined by requesting 
LISTX at compile time. 



But when using the assembler language 
overlay routine (OVRLAY) , it becomes: 



I CALL "OVRLAY" USING PROCESS-LABEL, 
I PARM-1, PARM-2. 



where PROCESS-LABEL contains the 
external-name OVERLAYB of the called 
program. 



However, the ENTRY statement of the 
called program is the same for both cases, 
i.e., ENTRY "OVERLAYB" USING PARAM-1, 
PARAM-2, whether it is called indirectly by 
the main program through the overlay 
program or called directly by the main 
program. 



I 



When preparing the control cards for the 
Linkage Editor, the programmer should be 
certain to include the assembler language 
subroutine with the main (root) phase. 



Note : An ENTRY which is to be called by 
OVRLAY must precede the first executable 
statement in the called procrram . 
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JOB CONTROL FOP ACCOBPLISKING OVERLAY 





COBOL 




© 


Main or Root 


- 


iOv 


Overlay Routine 


® 




®c 


- 


© 




Overlay Area 






















^ 
^ 






^ 

^ 










OVERLAY B 
Subprogram 




— (^ 








\^ 










J 








OVERLAY C 
Subprogram 
































OVERLAY D 












___ 


"Subprogram 









The job control statements reguired to 
accomplish the overlay illustrated in 
Figure 21 are shown in Figure 22. The 
PHASE statements specify to the Linkage 
Editor that the overlay structure to be 
established is one in which the called 
programs OVERLAYS, OVERLAYC, and OVERLAYB 
overlay each other when called during 
execution. 



Note ; The phase name specified in the 
P!IASE card must be the same as the value 
contained in the first argument for CALL 
"OVRLAY", i.e., PROCESS-LABEL, COKPUTE-TAX, 
etc., contain OVERLAYE, OVEELAYC, 
respectively, which are the names given in 
the PHASE card. 



Figure 21. Flow Diagram of Overlay Logic 



It is the programmer's responsibility to 
write the entire overlay, i.e., the COBOL 
main (or calling) prooram and an assembler 
language subroutine (for which a sample 
program is given in this chapter) that 
fetches and overlays the called programs. 
A calling seguence to obtain an overlay 
structure between three COBOL subprocraras 
is illustrated in Fiaure 23. 



// JOB OVERLAYS 
// OPTION LINK 

PHASE OVERLAY, ROOT 
// EXEC FCOBOL 

{COBOL Source for «ain Proaram MAINLINE} 

/* 

// EXEC ASSEMBLY 

[Source deck for Assembler Lanquaae Routine OVERLAY] 

/* 

PHASE 0VEHLAY3,* 
// EXEC FCOBOL 

{COBOL Source for Called Program OVERLAYS} 

/* 

PHASE OVERLAYC, OVERLAYE 
// EXEC FCOBOL 

{COBOL Source for Called Program OVEFLAYC} 

/* 

PHASE OVERLAYD, OVERLAYC 
// EXEC FCOBOL 

{COBOL Source for Called Proaram OVERLAYD} 

/* 

// EXEC LNKEDT 

// EXEC 

/* 



Figure 22. Job Control for Accomplishing Overlay 
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COBOL Program Main (Root o r Kain Program) 

IDENTIFICATION DIVISION. 
PROGRAM-ID. MAINLINE. 



ENVIRONMENT DIVISION. 



Tvmmii T\TTrx<?Xi-iM 



WORKING-STORAGE SECTION. 

77 PROCESS-LABEL PICTURE IS X (3) VALUE IS "OVERLAYB". 

77 PARAM-1 PICTURE IS X. 

77 PARAM-2 PICTURE IS XX. 

77 COMPUTE-TAX PICTURE IS X (8) VALUE IS "OVERLAYC". 

01 NAMET. 

02 EMPLY-NUMB PICTURE IS 9 (5) . 

02 SALARY PICTURE IS 9(4)V99. 

02 RATE PICTURE IS 9 (3) V99 . 

02 HOURS-REG PICTURE IS 9(3)V99. 

02 HOURS-OT PICTURE IS 9(2)V99. 
01 COMPUTE-SALARY PICTURE IS X (8) VALUE IS »OVERLAYD« 
01 NAMES. 

02 RATES PICTURE IS 9(6). 

02 HOURS PICTURE IS 9{3)V99. 

02 SALARYX PICTURE IS 9(2)V99. 



PROCEDURE DIVISION 



CALL «OVRLAY" USING PROCESS-LABEL, PARAM-1, PARAM-2. 



CALL "OVRLAY" USING COMPUTE-TAX, NAMET, 



CALL "OVRLAY" USING COMPUTE-SALARY, NAMES. 



Figure 23. Calling Sequence to Obtain Overlay Between Three COBOL Subprograms (Part 1 of 
3) 



I 
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COBOL subprogram B 

IDENTIFICATION DIVISION 
PBOGRAM-ID. OVERLAY 1. 



ENVIRONMENT DIVISION. 



DATA DIVISION, 



LINKAGE SECTION. 

01 PARAM-10 PICTURE X. 
01 PARAM-20 PICTURE XX, 



PROCEDURE DIVISION. 

PARA-NAME. ENTRY ••OVERLAYB" USING PARAM-10, PARAH-20, 



GOBACK. 



COBOL Subprogram C 

IDENTIFICATION DIVISION, 
PROGRAM-ID. 0VERLAY2. 



ENVIRONMENT DIVISION, 



DATA DIVISION, 



LINKAGE SECTION. 

01 NAMEX. 

02 EMPLY-NUMBX PICTURE IS 9(5). 
02 SALARYX PICTURE IS 9(4) V99. 
02 RATEX PICTURE IS 9(3)V99. 
02 HOURS-REGX PICTURE IS 9(3)V99. 
02 HOURS-OTX PICTURE IS 9(2)V99. 

PROCEDURE DIVISION. 

PARA-NAME. ENTRY "OVERLAYC" USING NAMEX, 



GOBACK, 



Figure 23. Calling Sequence to Obtain Overlay Between Three COBOL Subprograms 
(Part 2 of'3) 
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COBOL Subprogram D 

IDENTIFICATION DIVISION 
PROGRAM-ID. 0VERLAY3. 



ENVIRONHENT DIVISION. 



DATA DIVISION, 



LINKAGE SECTION 
01 NAMES. 

02 RATES PICTURE IS 9(6). 

02 HOURS PICTURE IS 9(3)V99. 

02 SALARYX PICTURE IS 9(2)V99. 

PROCEDURE DIVISION. 

PARA-NAME. ENTRY "OVERLAYD" USING NAMES 



GOBACK. 



Figure 23. Calling Sequence to Obtain Overlay Between Three COBOL Subprograms 
(Part 3 of 3) 



i 
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USING THE SEGMENTATION FEATURE 



COBOL segmentation 
subdivide logically a 
Procedure Division of 
program. All source 
the same segment-numb 
headers will be consi 
to be one segment. S 
can range from 00 thr 
possible to subdivide 
into a maximum of 100 



permits the user to 
nd physically the 

a COBOL object 
sections which contain 
er in their section 
dered at object time 
ince segment-numbers 
ough S9, it is 

any object program 

segments. 



Program segments may be of three types: 
fixed permanent, fixed overlayable, and 
independent as determined by the 
programmer's assignment of segment numbers. 

Segmentation of a program would be used 
when virtual storage is limited. In a real 
storage system, the following would apply: 

1. Fixed segments are always in real 
storage during the execution of the 
entire program, that is, they cannot 
be overlayed except when the system 
itself is executing another program, 
in which case fixed segments may be 
"rolled out." 

2. Fixed overlayable segments may be 
overlayed during program execution, 
but any such overlaying is transparent 
to the user, that is, they are 
logically identical to fixed segments, 
but physically different from them. 

3. Independent segments may be overlayed, 
but such overlaying will result in the 
initialization of that segment. 
Therefore, independent segments are 
logically different from fixed 
permanent/fixed overlayable segments, 
and physically different from fixed 
segments. 

In a virtual storage system, all 
logically "fixed" segments, that is, fixed 
permanent and fixed overlayable, are 
treated the same. They are both "paged in 
and out" as required for execution. 

In the same manner, independent segments 
are paged in and out; when they are paged 
in, however, they are brought back in the 
initial state. 

In DOS/VS COBOL, segments that are 
overlayed are not actually "paged out". 
All the variable data items associated with 
the segment are contained in one segment, 
which is considered the root segment. When 
a segment is "paged in", all the fields 
which must be reinitialized are contained 



in the root segment. Thus no fields in 
other than the root segment are modified, 



The program SAVECOEE could be segmented 
as illustrated in Figure 2^. 



IDENTIFICATION DIVISION. 
PBOGSAM-ID, SAVECOEE. 

I ENVIRONMENT DIVISION. 

OBJECT-COKPUTEE. IBB- 370. 
SEGMENT-LIMIT IS 15. 

DATA DIVISION. 



PEOCEDURE DIVISION. 
SECTION-1 SECTION 8, 



SECTION -2 SECTION 8 



SECTION-3 SECTION 16 



SECTION-4 SECTION 8. 



SECTION-5 SECTION 50, 



ISECTION-6 SECTION 16 



SECTION-7 SECTION 50- 



Figure 24. Segmenting the Program SAVECOEE 

Assuming that 12K of virtual storage is 
available for the program SAVECOEE, Figure 
25 shows the manner in which storage would 
be utilized. It is apparent from the 
illustration that SECTION-3, SECTION-6, and 
SECTION-7 cannot be in storage at the same 
time, nor can SECTION-3, SECTION-5 and 
SECTION-7 be in storage simultaneously. 

Sections in the permanent segment 
(SECTION-1, SECTION-2, and SECTION-it) are 
those which must be available for reference 
at all times, or which are referenced" 
frequently. They are distinguished here by 
the fact that they have been assigned 
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priority numbers less than the segment 
limit. 

Sections in the overlayable fixed 
segment are sections which are less 
frequently used. They are always made 
available in the state they were in when 
last used. They are distinguishable here 
by the fact that they have been assigned 
priority numbers greater than the segment 
limit but less than 49. 

Sections in the independent segment can 
overlay, and be overlaid by, either an 
overlayable fixed segment or another 
independent segment. Independent segments 
are those assigned priority numbers greater 
than 49 and less than 100, and they are 
always given control in their initial 
state. 



OPERATION 



Execution of the object program begins 
in the root segment. The first segment in 
the permanent segment is considered the 
root segment. If the program does not 
contain a permanent segment, the compiler 
generates a dummy segment which will 
initiate the execution of the first 
overlayable or independent segment. All 
global tables, literals, and data areas are 
part of the root segment. Called object 
time subroutines are also part of the root 
segment. Hhen CALL statements appear in a 
segmented program, subprograms are loaded 
with the fixed portion of the main program 
as if they had a priority of zero. 



Segmented programs must not be called by 
another program (segmented or not 
segmented) . If a segmented program calls a 
subprogram, the CALL statement may appear 
in any segment. However, the object module 
associated with the subprogram must be 
included in the root segment prior to the 
execution of the main program. This can be 
accomplished in either of two ways as 
follows: 



1. Produce object decks for both programs 
and place the one for the subprogram 
in the root segment: 



PHASE, ROOT 

BSD card for the root segment 

{object deck for the main program} 

{object deck for the subprogram) 

followed by a // EXEC LNKEDT and a // 
EXEC. 

2. Catalog the object module for the 

subprogram in the relocatable library 
prior to link editing the main 
program. Insert an INCLUDE card for 
the subprogram and an ENTRY card for 
the root phase into the linkage editor 
control cards for the root phase of 
the main program. The ENTRY card will 
cause the linkage editor to pass 
control to the main program at 
execution time. The Linkage Editor 
will search the relocatable library 
for the subprogram and include it with 
the root phase. 
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fixed portion 
{12K) 



5K 




SECTION-3 and SECTION-6 
are overlayable fixed segments 
(14 < segment limit < 50) 



SECTION-5 and SECTION-7 are 

independent segments 

(49 < segment limit < 100) 



Figure 25. Storage Layout for SAVECORE 



OOTPOT FBOH A SEGMENTED PROGRAM 



COHPILER OUTPUT 



The output produced by the compiler is 
an overlay structure consisting of multiple 
object modules preceded by linkage editor 
control statements. Segments whose 
priority is greater than the segment limit 
(or 49, if no SEGMENT-LIMIT clause is 
specified) consist of executable 
instructions only. 

The compiler generates each segment as a 
separate object module preceded by a PHASE 
card. The names appearing' on these PHASE 
cards (segment-naaes) conform to the 
following naming conventions: 

1 . The name of the root segment is the 
same as the program-name specified in 
the PROGRAM-ID clause. 

2. The name of each overlayable and 
independent segment is a combination 
of the program-name and the priority 
number of the segment. These names 
are formed according to the following 
rules: 



a. If the program-name is 6, 7, or 8 
characters in length, the 
segment-name consists of the first 
6 characters of program-name plus 
the 2-character priority number. 

b. If the program-name is less than 6 
characters in length, the priority 
number is appended after the 
program-name. 

c. Since the system expects the first 
character of PROGRAM-ID to be 
alphabetic, the first character, 
if numeric, is converted as 
follows: 

-> J 
1-9 -> A-I 

The hyphen is converted to zero if 
it appears as the second through 
eighth character. 

d. When DECK is specified, the 
punched object deck is sequenced 
according to segments. Columns 
73-74 contain the first two 
characters of the program-id, 
columns 75-76 contain the priority 
number of the segment, and columns 
77-80 contain the sequence number 
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of the card. The priority of the 
root segment is punched as 00. 

e. When the compiler option CATALR is 
in effect, the PHASE card for each 
segment is preceded by a CATSLR 
card with the same name. This 
will enable direct cataloging of 
the compiler-produced object 
module into the relocatable 
library from which a load module 
may be link edited into the 
core-image library. 

Note: Single-digit priority numbers 
are preceded by a zero. 



Warning : In order to avoid duplicate 
names, the programmer must be aware of the 
above naming conventions. If the last two 
characters of an 8-character PROGRAM-ID are 
numeric, these same two characters may not 
appear in the source program as a segment 
number. 



(^ ADTOLINK card for the Segmentation 
subroutine. 

(T) PHASE cards generated by the compiler 
for segments of priority 10, 47-50, 60, 
62, and 63. 

(4) Control card generated for the Sort 
Feature. This card is explained in 
"Sort in a Segmented Program." 

(5) Location of the entry point CURSEGH. 
Item 5 is explained in "Determining the 
Priority of the Last Segment Loaded 
into the Transient Area." 

(e) Load address of phase BIGJOBOO. Item 6 
is explained in "Sort in a Segmented 
Program. " 

Note: If the CATALR option of the CBL card 
is specified, the compiler generates CATALR 
cards in front of PHASE cards. 



Figure 26 is an illustration of the 
compiler output for the skeleton program 
shown in Figure 24. 



PHASE SAVECORE,ROOT 

{object module for the root segment 
(sections with priority-numbers less 
than the segment limit) including any 
programs called by SAVECORE} 



PHASE SAVEC016,* 

{object module for segments with a 
priority of 16 (two sections)} 



PHASE SAVECO50,SAVECO16 

{object module for segments with a 
priority of 50 (two sections)} 

I 

Figure 26. Compiler Output for SAVECORE 



Cataloging a Segmented Progra m 



When the CATAL option is used to catalog 
a segmented program, the following points 
should be observed: 

1. To avoid duplicate names, the 
programmer must be aware of the naming 
conventions used by the compiler (see 
"Compiler Output") because a 
segment-name may be the same as a 
phase-name already existing in the 
core image library. 

2. Since the PHASE card is generated by 
the compiler, the programmer must not 
specify a PHASE card for the program. 

To invoke a previously cataloged 
segmented program, the programmer must use 
the following control statement : 

// EXEC name 

where name is the program-name specified in 
the PROGRAM-ID clause'. 



LINKAGE EDITOR OUTPUT 



Figure 27 is an illustration of the 
input to the Linkage Editor and the phase 
map produced by the Linkage Editor 
resulting from the compilation and editins 
of the segmented program BIGJOB. The 
following text is an explanation of the 
figure. 



© 



1 ) PHASE card generated by the compiler 
for the root segment BIGJOB. 



Determining the Priority of the Last 
Segment Loaded into the Transient Area 



If a segmented program is abnormally 
terminated during execution, and the SYHDMP 
option has been specified, the CURRENT 
PRIORITY cell in the Task Global Table 
contains the priority of the last segment 
loaded into the transient area. If SYHDMP 
has not been specified, the priority of 
this segment can be determined as follows: 



1 . In the map of virtual storage 
ge W-Jial ed by the Linkage Editor, under 
the column LABEL, look for the name 
•CORSEGM* (see item 5 in Figure 27) . 

2. Associated with this label, in the 
column LOADED, is an address. 



• A PERFOEM statement that appears in a 
section whose priority-number is less 
than the segment limit can have within 
its range only (a) sections with 
priority-numbers less than 50, and (b) 
sections wholly contained in a single 
segment whose priority-number is 
greater than 49. 



3. At this location is stored the 

priority (one byte) of the segment 
current in the transient area. If 
this byte is X'OO*; no segment has 
been loaded into the transient area. 
This indicates that the error causing 
the dump occurred in the root segment 



SORT IN A SEGMENTED PROGRAM 



If a segmented program contains a SORT 
statement, the sort program will be loaded 
above the largest overlayable or 
independent segment as shown in Figure 28. 

The compiler accomplishes this by 
providing the following control statement 
at the end of the overlay structure: 

PHASE BIGJOBOO, transient area + L 

This card is illustrated in Figure 27, item 
4. The value of "L" in the figure is 
X»002F2» which is the length of the longest 
segment, BIGJOB47, rounded to the next 
half word boundary. Note that Linkage 
Editor relocates the phase BIGJOBOO to the 
next doubleword boundary (see Figure 27, 
item 6) . 



Using the PERFORM Statement in a Segmented 
Program 



When the PERFORM statement is used in a 
segmented program, the programmer should be 
aware of the following: 



Note 



As an extension to American 



National Standard COBOL, DOS/VS COBOL 
allows sections with any 
priority-number to fall within the 
range of a PERFORM statement. 



A PERFORM statement that appears in a 
section whose priority-number is equal 
to or greater than the segment limit 
can have within its range only (a) 
sections with the same priority-number 
as the section containing the PERFORM 
statement, and (b) sections with 
priority-numbers that are less than the 
segment limit. 



Note: As an extension to American 
National Standard COBOL, DOS/VS COBOL 
allows sections with any 
priority-number to fall within the 
range of a PERFORM statement. 



• When a procedure-name in a permanent 
segment (priority-number less than 
segment limit) is referred to by a 
PERFORM statement in an independent 
segment (priority-number greater than 
49) , the independent segment is 
reinitialized upon exit from the 
PERFORM. When a PERFORM statement 
in the overlayable-f ixed segment 
(priority-niimber greater than segment 
limit and less than 50) refers to a 
procedure-name in a permanent segment, 
the overlayable- fixed segment is not 
reinitialized upon exit from the 
PERFORM. 
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Figure 27. Link Editing a Segmented Program 



I ROOT I Including COBOL subroutines and called programs 
I 1 



I TRANSIENT | 
L )| AREA I Overlayable and independent segments 

I 1 

I SORT PROGRAM! 
I I 

L = length of the largest segment in bytes. 



Figure 26. Location of Sort Program in a Segmentation Structure 
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PROCESSING COBOL FILES ON MASS STORAGE DEVICES 



A mass storage device is one on which 
records can be stored in such a way that 
the location of any one record can be 
determined without extensive searching. 
Becords can be accessed directly rather 
than serially. 

The recording surface of a mass storage 
device is divided into many tracks. A 
track is defined as a circumference of the 
recording surface. The nusber of tracks 
per recording surface and the capacity of a 
track for each device are shown in Table 9. 



Table 9. Recording Capacities of Mass 
Storage Devices 



sequential, direct, indexed, and VSAM. VSAM 
is discussed in the chapter entitled "Virtual 
Storage Access Method (VSAM) . " 



r - -- -1 1 
1 Device | Capacity j 


12311 1200 tracks per surface; 3625 | 
1 1 bytes per track. | 


12314, |200 tracks per surface; 729U | 
|2319 1 bytes per track. | 


12321 1 100 tracks per strip; 2000 | 
1 1 bytes per track. I 


13330 1404 tracks per surface; 13030 I 
1 1 bytes per track. 1 


|3330-11* |808 tracks per surface; 13030 j 
1 1 bytes per track. 


|3340 |348 tracks per surface; 8368 | 
Model 35 j bytes per track. j 


|3340 1696 tracks per surface; 8368 | 
1 Model 70 1 bytes per track. 


'3350 |555 tracks per surface; 19069 | 
j 1 bytes per track. I 



*In the COBOL ASSIGN statement the 3330-11 
is specified as 333B. 

Each device has some type of access 
mechanism through which data is transferred 
to and from the device. The mechanisms are 
different for each device, but each 
mechanism contains a number of read/write 
heads that transfer data as the recording 
surfaces rotate past them. Only one head 
can transfer data (either reading or 
writing) at a time. 

FILE ORGANIZATION 

Records in a file must be logically 
organized so that they can be retrieved 
efficiently for processing. Four methods 
of organization for mass storage devices 
are supported by the DOS/VS COBOL compiler: 



SEQUENTIAL ORGANIZATION 

In a seguential file, records are 
organized solely on the basis of their 
successive physical location in the file. 
The records are read or updated in the same 
order in which they appear. 

Individual records cannot be located 
quickly. Records usually cannot be deleted 
or added unless the entire file is 
rewritten. This organization is used when 
most of the records in the file are 
processed each time the file is used. 



DIRECT ORGANIZATION 

A file with direct organization is 
characterized by some predictable 
relationship between the key of a record 
and the address of that record on a mass 
storage device. This relationship is 
established by the programmer. 

Direct organization is generally used 
for files where the time required to locate 
individual records must be kept to an 
absolute minimum, or for files whose 
characteristics do not permit the use of 
sequential or indexed organization. 

This organization method has 
considerable flexibility. The accompanying 
disadvantage is that although the Disk 
Operating System/Virtual Storage provides 
the routines to read or write a file of 
this type, the programmer is largely 
responsible for the logic and programming 
required to locate the key of a record and 
its address on a mass storage device. 

Note ; Direct organization is not supported 
on fixed block devices. 



INDEXED ORGANIZATION 

An indexed file is similar to a 
sequential file in that rapid sequential 
processing is possible. The indexes 
associated with an indexed file also allow 
quick retrieval of individual records 
through random access. Moreover, a 
separate area of the file is set aside for 
additions; this eliminates the need to 
rewrite the entire file when adding 
records, a process that would usually be 
necessary with a sequentially organized 
file. Althouqh the added records are not 
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physically in key sequence, the indexes are 
constructed in such a way that the added 
records can be quickly retrieved in key 
sequence, thus making rapid sequential 
access possible. 

In this method of organization, the 
system has control over the location of the 
individual records. Since the 
characteristics of the file are known, most 
of the mechanics of locating a particular 
record are handled by the system. 

Note ; Indexed organization is not supported 
on fixed block devices. 



DATA MANAGEMENT CONCEPTS 



The data management facilities of the 
Disk Operating System Virtual Storage are 
provided by a group of routines that are 
collectively referred to as the 
Input/Output Control System (IOCS) . A 
distinction is made between two types of 
routines: 

1. Physical IOCS (PIOCS) — the physical 
input/output routines included in the 
Supervisor. PIOCS is used by all 
programs run within the system. It 
includes facilities for scheduling 
input/output operations, checking for 
and handling error conditions related 
to input/output devices, and handling 
input/output interruptions to maintain 
maximum input/output speeds without 
burdening the programmer's problem 
program . 

2. Logical IOCS (LIOCS) — the logical 
input/output routines linked with the 
programmer's problem program. These 
routines provide an interface between 
the programmer's file processing 
routines and the PIOCS routines. 

LIOCS performs those functions that a 
programmer needs to locate and access 
a logical record for processing. A 
logical record is one unit of 
information in a file of similar 
units, for example, one employee's 
record in a master payroll file, one 
part-number record in an inventory 
file, or one customer account record 
in an account file. One or more 
logical records may be included in one 
physical record. LIOCS refers to the 
routines that perform the following 
functions : 

a. Blocking and deblocking records 

b. Switching between input/output 
areas when two areas are specified 
for a file 



c. Handling end-of-file and 
end-of-volume conditions 



d. Checking and writing labels 



A brief description of functions 
performed by LIOCS and their relationship 
to a COBOL program follows. 

Whenever COBOL imperative-statements 
(READ, WRITE, REWRITE, etc.) are used in a 
program to control the input/output of 
records in a file, that file must be 
defined by a DTP (Define The File) or, for 
VSAH, an ACB (Access Method Control Block) . 
A DTF or ACB is created for each file 
opened in a COBOL program from information 
specified in the Environment Division, FD 
entry, and input/output statements in the 
source program. The DTF for each file is 
part of the object module that is generated 
by the compiler. The ACB is generated at 
object time. They describe the 
characteristics of the logical file, 
indicate the type of processing to be used 
for the file, and specify the storage areas 
and routines used for the file. Further 
and more detailed onformation in 7SAM is to 
be found in the chapter "VSAM." 

One of the constants in the DTF table is 
the address of a logic module that is to be 
used at execution time to process that 
file. A logic module contains the coding 
necessary to perform data management 
functions required by the file such as 
blocking and deblocking, initiating label 
checking, etc. 

Generally, these logic modules are 
assembled separately and cataloged in the 
relocatable library under a standard name. 
At link edit time, the Linkage Editor 
searches the relocatable library using the 
virtual reference to locate the logic 
module. The logic module is then included 
as part of the program phase. Note that 
since the Autolink feature of the Linkage 
Editor is responsible for including the 
logic modules, the COBOL programmer need 
not specify any INCLUDE statements. 

The type of DTF table prepared by the 
compiler depends on the organization of the 
file and the device to which it is 
assigned. The DTF's used for processing 
files assigned to mass storage devices are 
as follows: 

DTFSD — Sequential organization, 
sequential access 

DTFDA — Direct organization, 

sequential or random access 

DTFIS — Indexed organization. 
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For a 3540 diskette unit, the DTP is 
DTFDO. More detail on this is given in the 
chapter "Processing 3540 Diskette Unit 
Files." 

The remainder of this chapter provides 
information about preparing programs which 
process files assigned to mass storage 
devices. Included are general descriptions 
of the organization, the COBOL statements 
that must be specified in order to build 
the correct DTF tables, and coding 
examples. 



SEOOENTIAL OBG&NIZATIOH fPTFSDl 



In a sequential file on a mass storage 
device, records are written one after 
another — track by track, cylinder by 
cylinder — at successively higher 
addresses. 

Records may be fixed-length, spanned, or 
variable-length, blocked or unblocked, or 
undefined. Since the file is always 
accessed sequentially, it is not formatted 
with keys. 

Processing a sequentially organized file 
for selected records is inefficient. If it 
is done infrequently, the time spent in 
locating the records is not significant. 
The slowest way is to read the records 
sequentially until the desired one is 
located. On the average, half of the file 
must be read to locate one record. 

Additions and deletions require a 
complete rewrite of a sequentially 
organized file on a mass storage device. 
Sequential organization is used on mass 
storage devices primarily for tables and 
intermediate storage rather than for master 
files. 

Sequentially organized files formatted 
with keys cannot be created using DTFSD. 
DTFDA may be used to create and access 
(sequentially or randomly)" such files. 



SELECT [OPTIONAL] file-name 



ASSIGN TO SYSnnn- 



Optional clauses : 



DT 



DA 



2311\ 
2314 I 
2321 I 
2319 I 
3330 >-S 
333B| 
3340 1 
3350 I 
FBAl/ 



I 



RESERVE Clause 
FILE-LIHIT Clause 
ACCESS MODE IS SEQUENTIAL 
PROCESSING MODE IS SEQUENTIAL 
RERUN Clause 
SAME Clause 

APPLY WRITE-ONLY Clause .. (create only) 
APPLY WRITE-VERIFY Clause (create or 
update only) 

Invalid clauses : 

ACCESS MODE IS RANDOM 
ACTUAL KEY Clause 
NOMINAL KEY Clause 
RECORD KEY Clause 
TRACK-AREA Clause 
MULTIPLE FILE TAPE Clause 
APPLY EXTENDED-SEARCH Clause 
APPLY CYL-OTERFLOW Clause 

(MASTER-INDEX] 
APPLY< > Clause 

(CYL-INDEX ) 

APPLY CORE-INDEX Clause 

DTFSD files may be opened as INPUT, 
OUTPUT, or I-O. When creating such a file, 
an INVALID KEY condition occurs when the 
file limit has been reached and an attempt 
is made to place another record on the mass 
storage device. The file limit is 
determined from the EXTENT control 
statements. 

When a DTFSD file is opened as OUTPUT, 
each WRITE, statement signifies the creation 
of a new record. When opened as I-O, each 
WRITE statement signifies that the record 
just read is to be rewritten. 



DIRECT ORGANIZATION (DTFDA) 



PROCESSING A SEQUENTIALLY ORGANIZED FILE 



To create, retrieve, or update a DTFSD 
file, the following specifications should 
be made in the source program: 



ENVIRONMENT DIVISION 
Required clauses : 



With direct organization, there is a 
definite relationship beteween the key of a 
record and its address. This relationship 
permits rapid access to any record if the 
file is carefully organized. The 
programmer develops a record address that 
ranges from zero to some maximum by 
converting a particular field in each 
record to a track address. Each byte in 
the address is a binary number. To 
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reference a particular record, the 
progranmer must supply both the track 
addtess and the identifier that makes each 
record unique on its track . Both the track 
address and the identifier are supplied by 
the programmer in the ACTUAL KEY clause. 
This will be discussed in detail later in 
this chapter. 

Hith direct organization, records may be 
fixed length, spanned or undefined. The 
records must be unblocked. RO (record 
zero) of each track is used as a capacity 
record. It contains the address of the 
last record written on the track, and is 
used by the system to determine whether a 
new record will fit on the track. The 
capacity records are updated by the system 
as records are added to the file. The 
capacity records do not account for 
deletions: as far as the system is 
concerned, once a track is full it remains 
full (even if the programmer deletes 
records) until the file is reorganized. 

Often, more records are converted to a 
given track address than will actually fit 
on the track. These surplus records are 
known as overflow records and are usually 
written into a separate area known as an 
overflow area. 

As already noted, the programmer has an 
unlimited choice in deciding where records 
are to be located in a directly organized 
file. The logic and programming are his 
responsibility . 

When creating or making additions to the 
file, the programmer must specify the 
location for a record (track address) and 
the identifier that makes each record^ on 
the track unique. If there is space on the 
track, the system writes the record and 
updates the capacity rGcord. If the 
specified track is full, a standard error 
condition occurs, and the programmer may 
specify another track address in his USE 
APTER STAHDAED ERROR declarative routine. 

In the case of one maximum size record 
per track (when spanned records are not 
specified) , the data length plus the length 
of the symbolic key cannot exceed the 
following values: 

2311 — 3605 bytes 
2314, 2319 ~ 7249 bytes 
2321 — 1984 bytes 
3330 ~ 12974 bytes 
3340 ~ 8293 bytes 
3350 — 18987 bytes 

When reading or updating the file, the 
programmer must supply the track address 
and the unique identifier on the track for 
the specific record being sought. The 
system locates the track and searches that 
track for the record with the specified 



identifier. If the record is not found, 
COBOL indicates this to the programmer by 
raising an INVALID KEY condition. Only the 
track specified by the programmer is 
searched. If EXTENDED-SEARCH is applied, 
the search for a specified record key begins 
on the track specified and continues until 
one of two conditions occurs: 

1 . The record is found. 

2. The end of the specified cylinder 
is reached. 

In the second case, the INVALID-KEY option 
of the READ or REWRITE is executed. To 
ensure file integrity, the upper limit of 
each extent of a file using EXTENDED- SEARCH 
must be the last track of a cylinder. 

Error recovery from a DTFDA file is 
described in detail in the chapter 
"Advanced Processing Capabilities." 



ACCESSING A DIRECTLY ORGANIZED FILE 



A directly organized file (DTFDA) may be 
accessed either sequentially or randomly. 

ACCESSING A DIRECTLY ORGANIZED FIL E 
SEQUENTIALLY : When reading a direct file 
sequentially, records are retrjpeved in 
logical sequence; this logical sequence 
corresponds exactly to the physical 
sequence of the records. To retrieve a 
DTFDA file sequentially, the following 
specifications are made in the source 
program: 

ENVIRONMENT DIVISION 

Required clauses : 

SELECT [OPTIONAL] file-name 



ASSIGN TO SYSnnn-DA- 




Optional claus es : 

FILE-LIMIT Clause 

ACCESS MODE IS SEOUENTIAL 

PROCESSING MODE IS SEQUENTIAL 

ACTUAL KEY Clause 

RERUN Clause 

SAME Clause 



{ 
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Invalid clauses ; 

EJJSERVE Clause 
RCCESS MODE IS RANDOM 
NOMINAL KEY Clause 
RECORD KEY Clause 
TRACK-AREA Clause 
MULTIPLE FILE TAPE Clause 
APPLY WRITE-ONLY Clause 
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APPLY CYL -OVERFLOW Clause 
APPLY EXTENDED- SEARCH Clause 
APPLY WRITE-VERIFY Clause 



("MASTER-INDEX) 
APPLY<^ > Clause 

(CYL-INDEX j 

APPLY CORE-INDEX Clause 

When DTFDA records are retrieved 
sequentially, the file may be opened only 
as INPUT. The Ax END condition occurs when 
the last record has been read and execution 
of another READ is attempted. 

Note that in the ASSIGN clause, an A 
must be specified for files with actual 
track addressing, and a D must be specified 
for files with relative track addressing. 



ACCESSING A DIRECTLY ORGANIZED FILE 
RANDOMLY ; To create a directly organized 
file randomly, the following specifications 
are made in the source program: 

ENVIRONMENT DIVISION 

Required clauses : 

SELECT file-name 



ASSIGN TO SYSnnn-DA- 



ACCESS MODE IS RANDOM 
ACTUAL KEY Clause 

Optional clauses : 

FILE-LIMIT Clause 

PROCESSING MODE IS SEQUENTIAL 

RERUN Clause 

SAME Clause 

APPLY WRITE-VERIFY Clause 

Invalid clauses : 

RESERVE Clause 
ACCESS MODE IS SEQUENTIAL 
NOMINAL KEY Clause 
RECORD KEY Clause 
TRACK-AREA Clause 
MULTIPLE FILE TAPE Clause 
APPLY WRITE-ONLY Clause 
APPLY EXTENDED-SEARCH Clause 
APPLY WRITE-VERIFY Clause 
APPLY CYL-OVERFLOW Clause 

(master -INDEX ) 
APPLY< > Clause 

CYL-INDEX ) 





APPLY CORE-INDEX Clause 

Note that in the ASSIGN clause, an A 
must be specified for files with actual 
track addressing, and a D must be specified 
for files with relative track addressing. 

To retrieve or update a directly 
organized file randomly, the following 
specifications must be made in the source 
program. 

ENVIRONMENT DIVISION 



Required clauses : 
SELECT file-name 

ASSIGN TO SYSnnn-DA- 



ACCESS MODE IS RANDOM 
ACTUAL KEY Clause 

Note that in the ASSIGN clause an A must 
be specified for files with actual track 
addressing, a D must be specified for files 
with relative track addressing, a must be 
specified for files with actual track 
addressing when the REWRITE statement is 
used, and W must be specified for files 
with relative track addressing when the 
REWRITE statement is used. 

The optional and invalid clauses are the 
same as those specified previously for 
creating a directly organized file. 

Exception : APPLY EXTENDED-SEARCH is 
optional when retrieving or updating a 
directly organized file randomly. 



ACTUAL KEY CLAUSE 



Note that the ACTUAL KEY clause is 
required for DTFDA files when ACCESS IS 
RANDOM, is optional for DTFDA files when 
ACCESS IS SEQUENTIAL, and is not used for 
DTFSD files. 

The actual key consists of two 
components. One component expresses the 
track address at which the record is to be 
placed for an output operation, or at which 
the search is to begin for an input 
operation. The track address can be 
expressed either as an actual address or as 
a relative address, depending upon the 
addressing scheme chosen when the file was 
created. The other component is associated 
with the record itself and serves as its 
unique identifier. The structures of both 
actual keys are shown in Figure 29. 
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Byte 



Byte 



Actual Key 



Actual Track | Record Identifier | 
Address | | 

. I I 



8 9 



263 



Actual Key 



f , 1 

(Relative (Record Identifier! 
(Track Address ( ( 

t t I 



4 5 



258 



Figure 29. Structures of the Actual Key 



through 258 bytes in length. It must be 
defined in the File Section, the Working- 
Storage Section, or the Linkage Section. 
The first four bytes of data-name are the 
track identifier. The identifier is used 
to specify the relative track address for 
the record and must be defined as an 
8-integer binary data item whose maximum 
value does not exceed 16,777,215. The 
remainder of data-name, which is 1 through 
254 bytes in length, is the record 
identifier. It represents the symbolic 
portion of the key field used to identify a 
particular record on a track. 

For a complete discussion of the ACTUAL 
KEY clause, see the publication IBH DOS 
Full American National Standard COBOL. 



The format of the ACTUAL KEY clause is: 

ACTUAL KEY IS data-name 

When actual track addressing is used, 
data-name may be any fixed item from 9 
through 263 bytes in length. It must be 
defined in the Working -Storage, File, or 
Linkage Section. The first eight bytes are 
used to specify the actual track address. 
The structure of these bytes and 
permissible specifications for the mass 
storage devices are shown in Figure 30. 
The programmer may select from 1 to 255 
bytes for the record identifier portion of 
the actual key field. 

Note ; If a SEEK statement is used when 
retrieving a direct file randomly, actual 
track addressing is required. 

When relative track addressing is used, 
data-name may be any fixed item from 5 

I 1 1 



Randomizing Techniques 



One method of determining the value of 
the track address portion of the field 
defined in the ACTUAL KEY clause is 
referred to as indirect addressing . 
Indirect addressing generally is used when 
the range of keys for a file includes a 
high percentage of unused values. For 
example, employee numbers may range from 
000001 to 009999, but only 3000 of the 
possible 9999 numbers are currently 
assigned. Indirect addressing is also used 
for nonnumeric keys. Key, in this 
discussion, refers to that field of the 
record being written that will be converted 
to the track address portion. 

Indirect addressing signifies that the 
key is converted to a value for the actual 
track address by using some algorithm 
intended to limit the range of addresses. 

1 1 1 
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Such an algorithm is called a randomizing 
technigue » Randomizing technigues need not 
produce a unique address for every record 
and, in fact, such technigues usually 
produce synonyms . Synonyms are records 
whose keys randomize to the same address. 

Two objectives must be considered in 
selecting a randomizing technique: 

1 . Every possible key in the file must 
randomize to an address within the 
designated range. 

2. The addresses should be distributed 
evenly across the range so that there 
are as few synonyms as possible. 

Note that one way to minimize synonyms 
is to allocate more space for the file than 
is actually required to contain all the 
records. For example, the percentage of 
locations that are actually used might be 
80% to 85% of the allocated space. 

When actual track addressing is used, 
the first eight bytes of the ACTUAL KEY 
field can be thought of as a "discontinuous 
binary address." This is significant to 
the programmer because he must keep two 
considerations in mind. First, the 
cylinder and head number must be in binary 
notation, so the results of the randomizing 
formula must be in binary format. Second, 
the address is "discontinuous" since a 
mathematical overflow from one element 
(e.g., head number) does not increment the 
adjacent element {e.g., cylinder number). 



DIYISION/REHAINDER METHOD ; One of the 
simplest ways to indirectly address a 
directly organized file is by using the 
division/remainder method. (For a 
discussion of other randomizing technigues, 
see the publication Introduction to IBH 
Direct Access Storage Devices and 
Organization Methods , Order No. 
GC20-1649.) 

1. Determine the amount of locations 
required to contain the data file. 
Include a packing factor for 
additional space to eliminate 
synonyms. The packing factor should 
be approximately 20% of the total 
space allocated to contain the data 
file. 

2. Select, from the prime number table, 
the nearest prime number that is less 
than the total of step 1. A p rime 
number is a number divisible only by 
itself and the integer 1. Table 10 is 
a partial list of prime numbers. 

3. Clear any zones from the first eight 
bytes of the actual key field. This 



can be accomplished by moving the key 
to a field described as COMPDTATIONAL. 



4. Divide the key by the prime number 
selected. 

5. Ignore the quotient; utilize the 
remainder as the relative location 
within the data file. 

6. (For actual track addressing only) 
Locate the beginning of the space 
available and manipulate the relative 
address, to the actual device address 
if necessary. 

For example, assume that a company is 
planning to create an inventory file on a 
2311 disk storage device. There are 8000 
different inventory parts, each identified 
by an 8-character part number. Dsing a 20% 
packing factor, 10,000 record positions are 
allocated to store the data file. 

Method A : The closest prime number to 
10,000, but under 10,000, is 9973. Dsing 
one inventory part number as an example, in 
this case #25DF3514, and clearing the zones 
we have 25463514. Dividing by 9973 we get 
a quotient of 2553 and a remainder of 2445. 
2445 is the relative location of the record 
within the data file corresponding to part 
number 25DF3514. The record address can be 
determined from the relative location as 
follows: 






1. 



3. 



(For actual track addressing only) 
Determine the beginning point for the 
data file (e.g., cylinder 100, track 
0). 

Determine the number of records that 
can be stored on a track (e.g., twelve 
per track on a 2314 disk pack, 
assuming each inventory record is 200 
bytes long) . 

Because each data record contains 
non-data components, such as a count 
area and interrecord gaps, track 
capacity for data storage will vary 
with record length. As the number of 
separate records on a track increases, 
interrecord gaps occupy additional 
byte positions so that data capacity 
is reduced. Track capacity formulas 
provide the means to determine total 
byte requirements for records of 
various sizes on a track. These 
formulas can be found in the 
publications IBM Component 
Descriptions , Order Nos. GA26-5988 
and GA26-3599. 

Divide the relative number (2445) by 
the number of records to be stored on 
each track. 
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4. (For actual track addressing only) 
The result, quotient = 203, is now 
divided into cylinder and head 
designation. Since the 2311 disk pack 
has ten heads, the quotient of 203 is 
divided by 10 to show: 

Cylinder or CC = 20 
Head or HH = 03 (high-order zero 
added) 



2. 



The number of records that may be 
contained on one track is twelve. 
Therefore, if 10,000 record locations 
are to be provided, 83't tracks must be 
reserved. 



The prime number nearest, but less 
than 83«», is 829. 



4B. (For relative track addressing only) 
The result, quotient = 203, now 
becomes the track identifier of the 
actual key. 

Method B ; Utilizing the same example, 
another approach will also provide the 
relative track address: 



3. Divide the zone-stripped key by the 
prime value. (In the example, 
25463514 divided by 829 provides a 
quotient of 30715 and a remainder of 
779. The remainder is the relative 
address.) 



* 
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Table 10. Partial List of Prime Numbers 
(Part 1 of 2) 



Table 10. Partial List of Prime Numbers 
(Part 2 of 2) 
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M . (For actual track addressing only) To 
convert the relative address to an 
actual device address, divide the 
relative address by the number of 
tracks in a cylinder. The quotient 
will provide the cylinder number and 
the remainder will be the track 
number. For example, the 2311 disk 
pack would utilize 779 as: 

Cylinder or CC = 77 
Track or HH = 9 



® 



If a record cannot fit on either 
cylinders 1 through 83, or on 
cylinder 84, the job is terminated. 



The standard error condition "no room 
found" is tested before control is 
given to the synonym routine. Other 
standard error conditions as well as 
invalid key conditions result in job 
termination. 



Figure 31 is a sample COBOL program 
which creates a direct file with actual 
track addressing using Method B and 
provides for the possibility of synonym 
overflow. Synonym overflow will occur if 
record randomizes to a track that is 
already full. The following description 
highlights the features of the example. 
Circled numbers on the program listing 
correspond to the numbers in the text. 



© 



© 



The value 10 is added to TRACK-1 to 
ensure that the problem program does 
not write on cylinder 0. Cylinder 
must be reserved for the Volume Table 
of Contents. 

• Since the prime number used as a 
divisor is 829, the largest possible 
remainder will be 828. Adding 10 to 
TRACK-1 adjusts the largest possible 
remainder to 838. 

If synonym overflow occurs, control is 
given to the error procedure 
declarative specified in the first 
section of the Procedure Division. 
The declarative provides that: 



• Any record which cannot fit on a 
track (i.e., tracks through 8 of 
any cylinder) will be written in the 
first available position on the 
following track (s) . 

• Any record which cannot fit within a 
single cylinder will be written on 
cylinder 84 (i.e., the cylinder 
overflow area) . 



© 



© 



© 



© 



EEROE-COND is the identifier which 
specifies the error condition that 
caused control to be given to the 
error declarative. EEROR-COND is 
printed on SYSLST whenever the error 
declarative section is entered. 
TRACK -ID and C-REC are also printed on 
SYSLST. They are printed before the 
execution of each WRITE statement. 
This output has been provided in order 
to facilitate an understanding of the 
logic involved in the creation of 
D-FILE. 



The first twelve records which 
randomize to cylinder 002 track 8 are 
actually written on track 8. 



The next twelve records which 
randomize to cylinder 002 track 8 are 
adjusted by the SYNONYM-ROUTINE and 
written on cylinder 002 track 9. 



The next twelve records which 
randomize to cylinder 002 track 8 are 
adjusted by the SYNONYH-ROOTINE and 
written on cylinder 84 track (i.e., 
the overflow cylinder) . 



The last two records which randomize 
to cylinder 002 track 8 are adjusted 
by the SYNONYF-ROUTIME and written on 
cylinder 84 track 1 (i.e., the 
overflow cylinder) . 



< 
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// JOB METHODBA 

// OPTION NODECK, LINK, LIST, LISTX,SYM, ERRS 

// EXEC FCOBOL 




1 IBM DOS VS COBOL REL 1.0 PP NO. 5746-CBl 08.47.44 10/04/73 

IDENTIFICATION DIVISION. 
PROGRiUl-ID. METHOD- B. 
ENVIRONMENT DIVISION. 
CONFIGURATION SECTION. 
SOURCE-COMPUTER. IBM-370. 
OBJECT-COMPUTER. IBM-370. 
INPUT-OUTPUT SECTION. 
FILE-CONTROL. 

SELECT D-FILE ASSIGN SYS015-DA-2314-A-MASTER 
ACCESS IS RANDOM 
ACTUAL KEY IS ACT-KEY. 

SELECT C-FILE ASSIGN TO SYS007-UR-2540K-S. 
DATA DIVISION. 
FILE SECTION. 
FD D-FILE 

LABEL RECORDS ARE STANDARD. 
01 D-REC. 

02 PART-NUM PIC X(8). 
02 NUM-ON-HAND PIC 9(4). 
02 PRICE PIC 9(5)V99. 
02 FILLER PIC X(181). 
FD C-FILE 

LABEL RECORDS ARE OMITTED. 
01 C-REC. 

02 PART-NUM PIC X(8). 
02 NUM-ON-HAND PIC 9(4)9. 
02 PRICE PIC 9(5)V99. 
WORKING-STORAGE SECTION. 
77 HD PIC 9 VALUE ZERO. 
77 SAVE PIC S^t8) COMP SYNC. 
77 QUOTIENT PIC S9(5) COMP SYNC. 
01 ERROR- COND. 

02 FILLER PIC 99 VALUE ZERO. 
02 ERR PIC 9 VALUE ZERO. 
02 FILLER PIC 9(5) VALUE ZERO. 
01 TRACK-1 PIC 9999. 
01 TRACK-ID REDEFINES TRACK-1. 
02 CYL PIC 999. 
02 HEAD PIC 9. 
01 KEY-1. 

PIC S999 COMP SYNC VALUE ZEROES. 
PIC S9 COMP SYNC VALUE ZERO. 
PIC S999 COMP SYNC. 
PIC S999 COMP SYNC. 
PIC X VALUE LOW- VALUE. 
-ID PIC X(8). 
01 KEY-2 REDEFINES KEY-1. 
02 FILLER PIC X. 
02 ACT-KEY PIC X(16) . 
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Figure 31. Creating a Direct File Using Method B (Part 1 of 4) 
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la'sA DOS Vti COaOii 



REL 1.0 



FP NO. 5746-CBi 



08.47.44 



10/04/73 



PROCEDURE DIVISION. 
DECLARATIVES. 

ERROR- PROCEDURE SECTION. USE AFTER STANDARD ERROR PROCEDURE 
ON D-FILE GIVING ERROR-COND. 



ERROR- ROUTINE. 

EXHIBIT NAMED ERROR-COND. 

IF ERR = 1 GO TO SYNONYM-ROUTINE ELSE 

DISPLAY 'OTHER STANDARD ERROR' REC-ID 
GO TO EOJ. 
SYNONYM-ROUTINE . 

IF CC = 84 AND HD = 9 DISPLAY 'OVERFLOW AREA FULL' 
GO TO EOJ. 

IF CC = 84 ADD 1 TO HD GO TO ADJUST-HD. 

IF HH = 9 GO TO END-CYLINDER. 

ADD 1 TO HH. 

GO TO WRITES. 
END-CYLINDER. 

MOVE 84 TO CC. 
ADJUST-HD. 

MOVE HD TO HH. 

GO TO WRITES. 
END DECLARATIVES. 
FILE-CREATION SECTION. 

OPEN INPUT C-FILE 
OUTPUT D-FILE. 
READS. 

READ C-FILE AT END GO TO EOJ. 

MOVE CORRESPONDING C-REC TO D-REC. 

MOVE PART-NUM OF C-REC TO REC-ID SAVE. 

DIVIDE SAVE BY 829 GIVING QUOTIENT REMAINDER TRACK-1 

ADD 10 TO TRACK-1. 

MOVE CYL TO CC. 

MOVE HEAD TO HH. 
WRITES. 

EXHIBIT NAMED TRACK- ID C-REC CC HH. 

WRITE D-REC INVALID KEY GO TO INVALID-KEY. 

GO TO READS. 
INVALID-KEY. 

DISPLAY 'INVALID KEY' REC-ID. 
EOJ. 

CLOSE C-FILE D-FILE. 

STOP RUN. 



© 



® 



/ 



® 



// LBLTYP NSD(Ol) 
// EXEC LNKEDT 



Figure 31. Creating a Direct File Using Method B (Part 2 of 4) 



« 



108 
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// ASSGN SYS007,X'00C' 

// ASSGN syS015,X'231' 

// DLBL MASTER,, 99/365, DA 

// EXTLNT SYS015, 111111, 1,0, 20, 840 

// EXEC 
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Figure 31. Creating a Direct File Dsing Method B (Part 3 of 4) 
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TRACK-ID = 0028 C-REC = 8290001825 
ERROR-COND = 00100000 



002 riri = 008 



TRACK-ID 
TRACK- ID 



0028 C-REC 
0028 C-REC 



ERROR-COND = 00100000 



TRACK- ID = 
TRACK-ID = 
TRACK- ID = 
TRACK- ID = 
TRACK- ID = 



0028 C-REC 
0011 C-REC 
0011 C-REC 
0011 C-REC 
0028 C-REC 



ERROR-COND = 00100000 



TRACK- ID = 

TRACK-ID = 



0028 C-REC 
0028 C-REC 



ERROR-COND = 00100000 



TRACK-ID = 
TRACK- ID = 



0028 C-REC 
0028 C-REC 



ERROR-COND = 00100000 



TRACK- ID = 
TRACK- ID = 
ERROR-COND 
TRACK-ID = 
TRACK- ID = 



0028 C-REC 
0028 C-REC 
= 00100000 
0028 C-REC 
0028 C-REC 



ERROR-COND = 00100000 
TRACK- ID = 0028 C-REC 



TRACK-ID = 
ERROR-COND 
TRACK-ID = 
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ERROR-COND 
TRACK- ID = 



0028 C-REC 
= 00100000 
0028 C-REC 
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= 00100000 
0028 C-REC 



TRACK-ID = 0028 C-REC 
ERROR-COND = 00100000 



TRACK-ID = 
TRACK- ID = 
ERROR-COND 
TRACK- ID = 



0028 C-REC 
0028 C-REC 
= 00100000 
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8290001835 
8290001836 
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8290001837 

8290001837 
8290001838 

8290001838 
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Figure 31. Creating a Direct File Using Method B (Part U of i») 
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Figure 32 is a sample COBOL program 
which creates a direct file with relative 
track addressing using Method B. The 
sample program provides for the possibility 
of synonym overflow. Synonym overflow will 
occur if a record randomizes to a track 
which is already full. The following 
discussion highlights some basic features. 
Circled numbers on the program listing 
correspond to numbers in the text. 



caused control to be given to the 
error declarative. ERROE-COND is 
printed on SYSLST whenever the error 
declarative section is entered. 
TRfiCK-ID and C-EEC are also printed on 
SYSLST before execution of each WRITE 
statement. This output has been 
provided in order to facilitate an 
understanding of the logic involved in 
the creation of D-FILE. 






© 



© 



© 



Since the prime number used as a 
remainder will be 828. 



If synonym overflow occurs, control is 
given to the USE AFTER STANDARD ERROR 
declarative specified in the first 
section of the Procedure Division. 
The declarative provides that any 
record that cannot fit on the track to 
which it randomizes will be written on 
the first subsequent track available. 



The standard error condition "no room 
found" is tested before control is 
given to the SYNONYH-ROUTINE. Other 
standard error conditions as well as 
invalid key conditions result in job 
termination (EOJ) . 

ERROE-COND is the identifier which 
specifies the error condition that 






© 



© 



© 



The first twelve records which 
randomize to relative track 18 are 
actually written on relative track 1i 



The next twelve records which 
randomize to relative track 18 are 
adjusted by the SYNONYM-ROUTINE and 
are actually written on relative track 
19. 



The next twelve records which 
randomize to relative track 18 are 
adjusted by the SYNONYM-ROUTINE and 
are actually written on relative track 
20. 



The last two records which randomize 
to relative track 18 are adjusted by 
the SYNONYM-ROUTINE and are actually 
written on relative track 21. 
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// JOB METHODBS 

// OP1ION NODECK, LINK, LIST, LISTX,SYM,ii.RRS 

// EXEC FCOBOL 



IBM DOS VS COBOL 



REL 1.0 



PP NO. 57it6-CBl 



08.UO.53 10/04/73 



CBL gUOTL 



IDENTIFICATION DIVISION. 
PROGRAM-ID. METHODB. 
ENVIRONMENT DIVISION. 
CONFIGURATION SECTION. 
SOURCE-COMPUTER. IBM- 370. 
OBJECT- COMPUTER. IEM-370. 
INPUT- OUTPUT SECTION. 
FILE-CONTROL. 

SELECT D-FILE ASSIGN TO SYS015-DA-2314-D-MASTER 

ACCESS IS RANDOM 

ACTUAL KEY IS ACT-KEY. 

SELECT C-FILE ASSIGN TO SYS007-UR-25aOR-S. 
DATA DIVISION. 
FILE SECTION. 
FD D-FILE 

LABEL RECORDS ARE STANDARD. 

D-REC. 

05 PART-NUM PIC X(8) . 

05 NUM-ON-HAND PIC 9(4). 

05 PRICE PIC 9(5)V99. 

05 FILLER PIC X(181). 

C-FILE 

LABEL RECORDS ARE OMITTED. 

C-kEC. 

05 PART-NUi-i PIC X(8). 

05 NUM-ON-HAND PIC 9(4). 

05 PRICE PIC 9(5)V99. 

05 FILLER PIC X(61). 
WORKING-STORAGE SECTION. 
77 SAVE PIC S9(8) COMP SYNC. 

QUOTIENT PIC S9(8) COMP SYNC. 

ACT -KEY. 

02 TRACK-ID PIC S9(8) COMP SYNC. 

02 REC-ID PIC X(8). 

ERKOR-COND. 

02 FILLER PIC 99 VALUE ZERO. 

02 ERR PIC 9 VALUE ZERO. 

02 FILLER PIC 9(5) VALUE ZEi^O. 



01 



FD 



01 



77 
01 



01 



Figure 32. Creating a Direct File with Relative Track Addressing Using Kethod B (Part 1 
of 4) 
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IBM DOS VS COBOL 



REL 1.0 



PP NO. 5746-CBl 



08.40.53 10/04/73 



PROCEDURE DIVISION. 

DECLARATIViiS. 

ERROR- PROCEDURE SECTION. USE AFTER STANDARD ERROR PROCEDURE 

ON D-FILE GIVING ERROR-COND. 
ERROR-ROUTINE. \ 

EXHIBIT UhlfiED ERROR-COND. I ^^ 

IF ERR = 1 GO TO SYNONYM-ROUTINE ELSE > \3) 

DISPLAY "OTHER STANDARD ERROR " REC-ID t 

GO TO EOJ. ' 

SYNONYM-ROUTINE . 

IF TRACK-ID IS LESS THAN 834, ADD 1 TO TRACK-ID. GO TO 
WRITES. 
END DECLARATIVES. 

OPEN INPUT C-FILE 

OUTPUT D-rlLE. 
READS. 

READ C-FILE AT END GO TO EOJ. 

MOVE CORRESPONDING C-REC TO D-REC. 

MOVE PART-NUM OF C-REC TO REC-ID, SAVE. 

DIVIDE SAVE BY 829 GIVING QUOTIENT REMAINDER TRACK-ID. 
WRITES . 

EXHIBIT NAMED TRACK-ID C-REC. 

WRITE D-REC INVALID KEY GO TO INVALID-KEY. 

GO TO READS. 
INVALID-KEY . 

DISPLAY "INVALID KEY " REC-ID. 
EOJ. 

CLOSE C-FILE D-FILE. 

STOP RUN. 



© 






u; 



// LBLTYP NSD(Ol) 
// EXEC LNKEDT 



Figure 32. Creating a Direct File with Relative Track Addressing Using Method B 
(Part 2 of 4) 
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IBM DOS VS COBOL 



REL 1 . 



PP NO. 5746-CBl 



08.40.53 



10/04/73 I 



// A.SSGJ SirS007,X' OOC 

// A.SSGN 3yS015,X'231' 

// DLBL MASTER,, 99/365, DA 

// EXTENT SySOlS, 111111,1', 0,20, 840 

// EXEC 



TKACK- 
TRACK- 
TRACK- 
TRACK- 
TRACK- 
TRACK- 
TRACK- 
TRACK- 
TkACK- 
TRACK- 
TRACK- 
TRACK- 
TkACK- 
TRACK- 
TRACK- 
TRACK- 
TRACK- 
TRACK- 
TRACK- 
TRACK- 
TRACK- 
TRACK- 
TRACK- 
ERROR- 
TRACK- 
TRACK- 
ERROR- 
TRACK- 
TRACK- 
ERROR- 
TRACK- 
TRACK- 
ERROR- 
TRACK- 



ID = 
ID = 
ID = 
ID = 
ID = 
ID = 
ID = 
ID = 
ID = 
ID = 
ID = 
ID = 
ID = 
ID = 
ID = 
ID = 
ID = 
ID = 
ID = 
ID = 
ID = 
ID = 
ID = 
COND 
ID = 
ID = 
COND 
ID = 
ID = 
CONu 
ID = 
ID = 
COtiD 
ID = 



00000000 
00000001 
00000018 
00000018 
00000018 
00000018 
00000018 
.00000018 
00000018 
00000018 
OCOOOOIS 
00000018 
00000018 
00000018 
00000018 
00000018 
00000018 
00000018 
000C0018 
00000018 
00000018 
00000018 
00000018 
= 00100000 
00000019 C 

00000018 C 
= 00100000 

00000019 C 

00000018 C 
= 00100000 

00000019 C 

00000018 C 
= 00100000 

00000019 C 



■REC 
•REC 
•REC 
•REC 
-REC 
■REC 
■REC 
-REC 
•REC 
■REC 
■REC 
■REC 
■REC 
■REC 
-REC 
■REC 
■REC 
-REC 
■REC 
■REC 
■REC 
•REC 
■REC 

■REC 
■REC 

■REC 

■REC 

■REC 
■REC 



82900000 

82900001 

8290001801 

8290001802 

8290001803 

8290001804 

8290001805 

8290001806 

8290001807 

8290001808 

8290001809 

829000181V. 

8290001811 

8290001812 

8290001813 

8290001814 

8290001815 

8290001816 

8290001817 

8290001818 

8290001819 

8290001820 

8290001821 

8290001821 
8290001822 

8290001822 
8290001823 

8290001823 
8290001824 



® 



® 



-REC = 8290001824 



Figure 32. Creating a Direct File vith Relative Track Addre: 
(Part 3"of 4) 
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IBM DOS VS COBOL 



REL 1.0 



PP NO. 5746-CBl 



08.40.53 10/04/73. 



TRA.CK- 
ERROR- 
TrtACK- 
TRACK- 
ERROR- 
TRACK- 
TRACK- 
ERROR- 
TRACK- 
TRACK- 
ERROR- 
TRACK- 
TRACK- 
ERROR- 
TRACK- 
TRACK- 
ERROR- 
TkACK- 
TRACK- 
ERROR- 
TRACK- 
TRACK- 
ERROR- 
TRACK- 
TRACK- 
ERROR- 
TRACK- 
TRACK- 
ERROR- 
TRACK- 
TRACK- 
ERROR- 
TRACK- 
TRACK- 
ERROR- 
TRACK- 
TRACK- 
ERROR- 
TRACK- 
TRACK- 
ERROR- 
TRACK- 



XD = 
COND 
ID = 
ID = 
COND 
ID = 
ID = 
COND 
ID = 
ID = 
COND 
ID = 
ID = 
COND 
■ID = 
ID = 
■COiMD 
ID = 
ID = 
COND 
■ID = 
ID = 
COND 
■ID = 
■ID = 
COND 
ID = 
LO = 
•COND 
ID = 
■ID = 
COtMD 
■ID = 
■ID = 
COND 
ID = 
■ID = 
COND 
•ID = 
ID = 
•COND 
ID = 



00000018 C 
= 00100000 

00000019 C 

00000018 C 
= 00100000 

00000019 C- 

00000018 C 
= 00100000 

00000019 C 

00000018 C 
= 00100000 

00000019 C- 

00000018 C 
= 00100000 

00000019 C 

00000018 C 
= 00100000 

00000019 C 

00000018 C- 
= 00100000 

00000019 C 

00000018 C 
= 00100000 

00000019 C 

00000018 C 
= 00100000 

00000019 C 

00000018 C 
= 00100000 

00000019 C 

00000018 C 
= 00100000 

00000019 C 

00000018 C 
= 00100000 

00000019 C 

00000018 C 
= 00100000 

00000019 C 

00000018 C 
= 00100000 

00000019 C 



-EEC = 8290001825 



REC 
REC 



■PEC 
•REC 



■REC 
•REC 



■REC 
•REC 



•REC 
•REC 



•REC 
REC 



•REC 
■REC 



•REC 
•REC 



•REC 
•REC 



■REC 
■REC 



■REC 
•REC 



■REC 
•REC 



•REC 

■REC 



8290001825 
8290001826 



8290001826 
8290001827 



8290001827 
8290001828 



8290001828 
8290001829 



8290001829 
8290001830 



8290001830 
8290001831 



8290001831 
8290001832 



8290001832 
8290001833 



8290001833 
8290001834 



8290001831* 
8290001835 



8290001835 
8290001836 



8290001836 
8290001837 



8290001837 
8290001838 






(J) 



■REC = 8290001838 



Figure 32. Creating a Direct File with Relative Track Addressing Using Method B 
(Part 4 of k) 
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ACTUAL TBACK ADDRESSING CONSIDERATIONS FOR 
SPECIFIC DEVICES 



Randomizing for the 2311 Disk Drive 



When randomizing for the 2311 Disk 
Drive, it is possible to circumvent the 
discontinous binary address by coding the 
randomizing formula in decimal arithmetic 
and then converting the results to binary. 
This can be done by setting aside a decimal 
field with the low-order byte reserved for 
the head number, and the high-order bytes 
reserved for the cylinder number. A 
mathematical overflow from the head number 
will now increment the cylinder number and 
produce a valid address. The low-order 
byte should then be converted to binary and 
stored in the HH field, and the high-order 
bytes converted to binary and stored in the 
CC field of the actual key field. 



The programmer can make another use of 
this decimal track address. He may wish to 
reserve the last track of each cylinder for 
synonyms. If this is the case, he is in 
effect redefining the cylinder to consist 
of nine tracks rather than ten tracks. The 
2311 cylinder could then be thought of as 
consisting of track numbers, as follows: 



Cylinder Cylinder 1 Cylinder 2 



Track 
Numbers 



I 



19 



118 

19 

120 



Randomizing to the 2311 Disk Drive 
should present no significant problems if 
the programmer using direct organization is 
completely aware that the cylinder and head 
number give him a unique track number. To 
illustrate, the 2311 could be thought of as 
consisting of tracks numbered as follows: 



Track 
Numbers 



Cylinder Cylinder 1 Cylinder 2 
I I 10 120 
i I I 



I 8 



117 



126 



If the programmer randomizes to relative 
track number 20, he can access it by 
dividing the track address by the number of 
tracks (9) in a cylinder. The quotient now 
becomes the cylinder number, and the 
remainder becomes the head number. 



2 = cylinder number 



9 )0020 
18 



2 = head number 



I 9 



19 



129 



If the randomizing formula resulted in 
an address of cylinder 001, head 9: 

Cylinder | Head 
Number | Number 

—f 



001 



this would be a reference to track 19. 
This fact allows the programmer to ignore 
the discontinuous cylinder and head number, 
If his formula resulted in an address of 
0020, this would result in accessing 
cylinder 2, head 0, the location of track 
20. 



To simplify randomizing, an algorithm 
must be developed to generate a decimal 
track address. This track address can then 
be converted to a binary cylinder number 
and head number. In addition, tracks can 
be reserved by dividing the track address 
by the number of tracks in a cylinder. The 
same concepts will hold true for devices 
such as the 2314, 3330, or 3340. For 
example, an algorithm can be developed 
using 20 tracks per cylinder and dividing 
by the closest prime number less than 20. 
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Randomizing for the 2321 Data Cell 



The track reference field for the 2321 
Data Cell is composed of the following 
discontinuous binary address: 

sub 
cell cell strip cyl. head record 



1 1 I 
1 1 1 


1 
1 


1 




1 


... ., 

1 


i 




1 


1 1 I 
1 H 1 B j B 


1 

1 c 


1 
1 


C 


1 

1 H 


1 

1 H 


1 
J 


R 


1 

1 


1 t 1 


i 


...X 




1 


1 


1 




J 



0-9 0-19 0-9 0-4 0-19 



At first glance, this presents an almost 
impossible randomizing task; but since each 
strip includes 100 tracks that are 
accessible through cylinder and head 
number, the 2321 Data Cell can be 
considered to consist of consecutively 
numbered tracks. 



Tracks 




>199999 



Strip 





1 

9 

10 

19 

100 

199 

1999 



It can be seen that relative track 20 is 
located on cylinder 1, head of some 
particular strip. Its address can be 
calculated by dividing by 20. 



20 



1 = cylinder number 

^20 
20 

= head number 



Thus, relative track number 120 will be 
located on strip 1, cylinder 1, head of 
some subcell . Note that the strip number 
is given by the hundreds digit, and the 
cylinder and head number are derived by 
dividing the two low-order digits by 20. 

The same relationship holds true for 
relative track number 900. It is located 
on strip 9, cylinder 0, track 0. Again, 
the hundreds digit gives the strip number, 
and dividing the two low-order digits by 20 



results in a guotient and remainder of 
zero. 

This relationship holds true through a 
relative track number of 19999, which is 
the number of tracks that can be contained 
on one cell of a data cell array. By 
applying the foregoing rules, an address of 
subcell 19, strip 9, cylinder 4, head 19 is 
derived. 

Thus, by randomizing to a 5-digit 
decimal track number, the programmer will 
be able to access the 20,000 tracks 
(40,000,000 characters) contained in a 
cell. 

The thousands digits would represent the 
subcell number, the hundreds digit the 
strip number, and the guotient and 
remainder of the two low-order digits 
divided by 20 would represent the cylinder 
and head number. Each one of these 
resulting decimal digits would then be 
converted to binary and placed in the 
appropriate location in the track reference 
field. 






There is a total of 200,000 
data cell array. To derive val 
that cross cell boundaries, the 
should randomize to a 6-digit d 
address. The highest address p 
should be 199,999. To convert 
data cell address, similar rule 
this case, the programmer must 
three high-order digits by 20: 

9 = cell 



tracks per 
id addresses 

programmer 
ecimal track 
ossible 
this to a 
s apply. In 
divide the 



20 f 199 
180 



19 = subcell 



The guotient becomes the cell number and 
the remainder becomes the subcell number. 
The hundreds digit is still the strip 
number, and the cylinder and head number 
can be derived as previously illustrated. 
The resulting address is 0091994190 and 
would appear in the first eight bytes of 
the actual key field as follows: 

sub 



cell cell strip cyl. head 



1 ■ 

1 H 
1 


1 B 
1 


-T 

1 B 
1 


1 C 1 C 
i 1 


■-r ■■ 
1 H 
1 


1 H 
1 


1 R 


— 1 

1 
t 


1 

1 

I 


1 
1 

L 


1 

1 9 

t 


1 19 1 9 


1 

1 ^ 


1 19 


1 


1 

1 



Randomizing to the data cell can be 
accomplished by developing an algorithm to 
generate decimal track addresses. The use 
of the foregoing rules makes it possible to 
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convert these generated track addresses to 
the appropriate discontinuous binary 
address. 



INDEXED ORGANIZATION (DTFIS) 



An indexed file is a se 
with indexes that permit r 
individual records as well 
sequential processing. Er 
a DTFIS file is described 
chapter "Advanced Processi 
An indexed file has three 
a prime area, indexes, and 
area. Each area is descri 
below. 



guential file 
apid access to 

as rapid 
ror recovery from 
in detail in the 
ng Capabilities." 
distinct areas: 

an overflow 
bed in detail 



PBTME AFEA 



When the file is first created, or when 
it is subsequently reorganized, records are 
written in the prime area. Until the prime 
area is full, additions to the file may 
also be written there. The prime area may 
span multiple volumes. Note that the last 
track of the prime area may not be used by 
the COBOL programmer. 



The records in the prime area must be 
formatted with keys, and must be positioned 
in key sequence. The records may be 
blocked or unblocked. If records are 
blocked, each logical record within the 
block contains its key, and the key area 
for the block contains the key of the 
highest record in the block. The Disk 
Operating System Virtual Storage permits 
fixed-length records only. Figure 33 shows 
the formats of blocked and unblocked 
records on a track . 



Unblocked Records 



I KEY NUMBER I 
I i_ 



I COUNT I KEY I DATA | 

J I I L 



T 1 1 r 

I COUNT I KEY I DATA | 



-Logical record (key embedded) 



-Key of logical record 



-Highest key on track 



Blocked Records 



I KEY NUMBER I 

I L. 



T 1 1 1 r 1 r 

I COUNT I KEY I DATA | DATA | DATA | | 

J I I I I I L. 



A 



' Logical records with embedded keys 

-Key of last logical record in block 



-Highest key on track 



Figure 33. Formats of Blocked and Unblocked Records 
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INDEXES 



There are three possible levels of 
indexes for a file with indexed 
organization: a track index, a cylinder 
index, and a master index. They are 
created and written by the system when the 
file is created or reorganized. 



Track Index 



This is the lowest level of index and is 
always present. There is one track index 
for each cylinder in the prime area. It is 
always written on the first track of the 
cylinder that it indexes. 

The track index contains a pair of 
entries for each prime data track in the 
cylinder: a normal entry and an overflow 
entry. The normal entry contains the home 
address of the prime track and the key of 
the highest record on the track. The 
overflow entry contains the highest key 
associated with that track and the address 
of the lowest record in the overflow area. 
If no overflow entry has yet been made, the 
address of the lowest record in the 
overflow area is the dummy entry X»FF». 



Cylinder Index 



The cylinder index is a higher level of 
index and is always present. Its entries 
point to track indexes. There is one 
cylinder index for the file. It is written 
on the device specified in the APPLY 
CYL-IBDEX clause. If this clause is not 
specified, the cylinder index is written on 
the same device as the prime area. 



be specified in the source program. When 
this clause is specified, the cylinder 
index is placed on the same device as the 
master index. 



Note ; The indexes are terminated by a 
dummy entry containing a key composed of 
all ones (bits) . To avoid any possibility 
of errors, the user should not specify a 
key of all ones (HIGH VALUES) for any of 
his records. 



OYEEFLOW AEEA 



There are two types of overflow areas: 
a cylinder overflow area and an independent 
overflow area. Either or both may be 
specified for an indexed file. Records are 
written in the overflow area (s) as 
additions are made to the file. 



Cylinder Overflow Area 



A certain number of whole tracks are 
reserved in each cylinder for overflow 
records from the prime tracks in that 
cylinder. The programmer may specify the 
number of tracks to be reserved by means of 
the APPLY CYL-07ERFL0W clause. If he 
specifies as the number of tracks in this 
clause, no cylinder overflow area is 
reserved. If the clause is omitted, 20% of 
each cylinder is reserved for overflow. 
For the 3330, three tracks of each cylinder 
will be reserved for overflow. For the 
3340, two tracks of each cylinder will be 
reserved for overflow. When an ISM!! file 
has been created with the APPLY CYL-OVERFLOW 
clause all FD's, which use the same file, 
must specify the same number of cylinder 
overflow tracks. 



^HR 



Master Index 



Independent Overflow Area 



The master index is the highest level 
index and is optional. It is used when the 
cylinder index is so long that searching it 
is very time consuming. It is suggested 
that a master index be requested when the 
cylinder index occupies more than four 
tracks. (A master index consists of one 
entry for each track of the cylinder 
index.) 

The DOS/VS System permits one level of 
master index for the file and requires that 
it be written immediately before the 
cylinder index. If a master index is 
desired, the APPLY SASTEB-INDEX clause must 



Overflow records from anywhere in the 
prime area are placed in a certain number 
of cylinders reserved soley for this 
purpose. The size and location of the 
independent overflow area can be specified 
if the programmer includes the proper job 
control EXTENT cards. The area must, 
however, be on the same mass storage device 
type as the prime area. 

A suggested approach is to have cylinder 
overflow areas large enough to contain the 
average number of overflow records caused 
by additions and an independent overflow 
area to be used as the cylinder overflow 
areas are filled. 
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PRIHE DATA AREA 
Track No. 



0001 lOOOOII 



(000031 
t I 



1000091 



lOOOIOl 
I I 



New record- 



Original record moved up- 



0002 



1000161 
I f 



1000171 
I I 



1000251 
I I 



OVERFLOW AREA 



1000141 
I I 



-Record removed from Track 0001 



loooni 



1000271 
I I 



Figure 34. Adding a Record to a Prime Track 



Adding Records to an Indexed File 



A new record added to an indexed file is 
placed into a location on a track in the 
prime area determined by the value of its 
key field. If records in the file were 
placed in precise physical sequence, the 
addition of a new record would require the 
shifting of all records with keys higher 
than that of the one inserted. However, 
indexed organization allows a record to be 
inserted into its proper position on a 
track, with the shifting of only the 
records on that track. Any records for 
which there is no space on that track are 
then placed in an overflow area, and become 
overflow records. Overflow records are 
always fixed-length, unblocked records, 
formatted with keys. 

As records are added to the overflow 
area, they are no longer in key sequence. 
The system ensures, however, that they are 
always in logical sequence. 

Figure 34 illustrates the addition of a 
record to a prime track. 

The new record (00010) is written in its 
proper sequential location on the prime 
track. The rest of its prime records are 



moved up one location. The bumped record 
(00014) is written in the first available 
location in the overflow area. The record 
is placed in the cylinder overflow area for 
that cylinder, if a cylinder overflow area 
exists and if there is space in it; 
otherwise, the record is placed in the 
independent overflow area. The first 
addition to a track is always handled in 
this manner. Any record that is higher 
than the original highest record on the 
preceding track, but lower than the 
original highest record on this track, is 
written on the prime track. Record 00015, 
for example, would be written as the first 
record on track 0002, and record 00027 
would be bumped into the overflow area. 



Subsequent additions are written either 
on the prime track where they belong or as 
part of the overflow chain from that track. 
If the addition belongs between the last 
prime record on a track and a previous 
overflow from that track (as is the case 
with record 00013) , it is written in the 
first available location in the overflow 
area on an empty track, or on a track whose 
first record has a numerically lower key. 
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If the addition belongs on a prime track 
(as would be the case vfith record 00005) , 
it is written in its proper sequential 
location on the prime track. The bumped 
record (record 00011) is written in the 
overflow area. 



fl record with a key higher than the 
current highest key in the file is placed 
on the last prime track containing data 
records. If that track is full, the record 
is placed in the overflow area. 



ACCESSING AN INDEXED FILE (DTFIS) 



Invalid clauses ; 

ACCESS HODE IS RANDOH 
ACTOAL KEY Clause 
TRACK-AREA Clause 
HDLTIPLE FILE TAPE Clause 
APPLY WRITE-ONLY Clause 
APPLY EXTENDED-SEARCH Clause 
APPLY CORE-INDEX Clause 

ACCESSING AN INDEXED FILE RANDOMLY ; A 
randomly-accessed indexed file may be read, 
updated, or added to. The following 
specifications may be made in the source 
program ; 

ENYIRONHENT DIYISION 

Required clauses: 



i 



An indexed file may be accessed both 
sequentially and randomly. 



ACCESSING AN INDEXED FILE SEQUENTIALLY ; An 
indexed file may only be created 
sequentially. It can also be read and 
updated in the sequential access mode. The 
following specifications may be made in the 
source program. 



SELECT [OPTIONAL] file-name 



ASSIGN TO SYSnnn-DA- 



ACCESS IS RANDOM 
NOMINAL KEY Clause 
RECORD KEY Clause 



2311 
23U 
'2321 
2319 
3330 
3340 



-I 



Optional clauses; 



ENVIRONMENT DIVISION 



Required clauses ; 

SELECT [OPTIONAL] file-name 

2311 

12314, 
ASSIGN TO SySnnn-DA-J2321V- I 

\2319i 

f3330' 

.3340 
RECORD KEY Clause 

NOMINAL KEY Clause (when reading, if the 
START statement is used) 



O ptional clauses : 

FILE-LIMIT Clause 

ACCESS MODE IS SEQUENTIAL 

PROCESSING MODE IS SEQUENTIAL 

RERUN Clause 

SAME Clause 

APPLY WRITE-TERIFY Clause (create and 

update) 
APPLY CYL-OVEHFLOH Clause (create) 

(MASTER-INDEX] 

APPLY < Vciause 

(CYL-INDEX ) 

RESERVE Clause 



FILE LIMIT Clause 

PROCESSING MODE IS SEQUENTIAL 

TRACK-AREA Clause 

RERUN Clause 

SAME Clause 

APPLY WRITE VERIFY Clause 

APPLY CYL-07ERFL0W Clause 

APPLY CORE-INDEX Clause 

'MASTER-INDEX) 
APPLY < > Clause 

CYL-INDEX ) 

Invalid clauses ; 

RESERVE Clause 

ACCESS MODE IS SEQUENTIAL 

ACTUAL KEY Clause 

MULTIPLE FILE TAPE Clause 

APPLY EXTENDED-SEARCH Clause 



When creating an indexed file, the only 
key clause required is the RECORD KEY 
clause. The data-name specified in this 
clause is the name of the field within the 
record that contains the key. Keys must be 
in ascending numerical order when creating 
an indexed file. 
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If a START statement is used when 
retrieving an indexed file sequentially, 
the NOMINAL KEY clause is required. 

When accessing an indexed file randomly, 
both the NOHINAL KEY and RECORD KEY clauses 
are required. When reading the file, the 
data-name specified in the NOMINAL KEY 
clause is the key of the record which is 
being retrieved. The data-name specified 
in the RECORD KEY clause is the name of the 
field within the record that contains this 
key. 

When adding records to an indexed file, 
the data-name specified in the NOMINAL KEY 
clause is the key for the record being 
written and is used to determine its 
physical location. The data-name specified 
in the RECORD KEY clause specifies the 
field in the record that contains the key. 

Note: If an INVALID KEY exit is taken on a 
START statement, the key value in the 
NOMINAL KEY data-name should be corrected 



and another START statement issued to 
ensure correct retrieval of blocked 
records. 



Improving Efficiency 



When processing an indexed file, the 
following source language Environment 
Division clauses may be used to improve 
efficiency: 



TRACK-AREA Clause 
APPLY CORE-INDEX Clause 



For additional details, see the 
publication IBM DOS Full American National 
Standard COBOL . 
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PROCESSING 3540 DISKETTE UNIT FILES 



The DOS/VS Compiler supports 3540 
Diskette unit file management. This device 
is quite different from standard direct 
access devices as it does not access data 
randomly. The medium used for reading and 
writing is a diskette which can be easily 
mailed from one location to another. 

Data can be recorded on the 3540 
diskette in two ways: 

1. Keypunching on the diskette via the 
3740 processing device. 

2. Writing sequential data sets on the 
diskette via the 3540 Diskette unit 
attached to a System/370. 

DOS/VS COBOL processing applies only to 
the processing of data on the diskette by 
the 3540 Diskette unit. 

For the use of system files on diskette, 
see DOS/VS System Management Guide . 



FILE PROCESSING 



File processing for the 3540 is 
sequential only. Only fixed-length 
physical records can reside on the 
diskette. Logical blocking of records is 
an available function and will be discussed 
in the section entitled "Cobol Language 
Considerations . " 

The system interfaces with the COBOL 
object module through DTFDU, (generated as 
part of the object module) , and DUHOD logic 
modules (used to perform actual I-O 
processing) . The generated DTFDU will 
correspond to a DTFDU generated by the 
DTFDU macro (described in DOS/VS Supervisor 
and 1-0 Macros ) with the exceptions 
specified later in this section. 

The physical considerations of the 3540 
diskette include: 

• The diskette is divided into character 
sectors with each sector containing 128 
characters. 



• Blocking factors can be only 1, 2, 13, 
or 26 records. 

Files may be extended to additional 
diskettes if one diskette is too small. 
This is done automatically by LIOCS if DLBL 
and EXTENT cards are provided for 
additional processing. There is no user 
program control to force end of volume for 
this device. 

File labels exist on the 354 Diskette 
for each file, but no user control or 
processing of these labels is provided by 
the DOS/VS system. Label management will 
be handled strictly by LIOCS. The user 
will only have to provide the name for the 
file in the DLBL control card. 



COBOL LANGUAGE CONSIDERATIONS 

ENVIRONMENT DIVISION 

The following format of the SELECT 
statement applies to the 3540: 

Required clauses : 

SELECT [OPTIONAL] file-name 

ASSIGN TO SYSnnn-(UTh3540-S[-name] 



i 



;nnn-^T>-: 



Sort work files may not be assigned to 
the 3540. A 3540 may not be a checkpoint 
device. 

Optional clauses : 

RESERVE clause 

ACCESS MODE IS SEQUENTIAL Clause 

PROCESSING MODE IS SEQUENTIAL clause 

RERUN ON system-name EVERY integer 
RECORDS OF file-name 

(System-name cannot specify 3540; 
file-name can refer to 3540 file; 
checkpoint records cannot be taken on 
a diskette, but a diskette can be used 
to control when checkpoints are 
taken.) 

SAME clause 

FILE LIMIT clause 

Invalid Clauses: 



• Each record may occupy no more than one 
sector, and may bs from 1 to 128 
characters long. 

• Each record in a file must be the same 
size. 



APPLY WRITE-ONLY clause (only 
fixed-length records allowed) 

APPLY WRITE-VERIFY clause (function not 
supported) 

ACCESS MODE IS RANDOM clause 

ACTUAL KEY clause 
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NOMINAL KEY clause 

RECORD KEY clause 

TRACK-ABEA clause 

MULTIPLE FILE TAPE clause 

RERON clause (see restrictions above) 

APPLY EXTENDED-SEARCH clause 

APPLY CYL-OVERFLOW Clause 



(master-index) 

APPLY < >clause 

(CYL-INDEX ) 

APPLY CORE-INDEX clause 

DATA division 

The following restrictions apply to the 
FD and record description for a 3540 file: 

• Recording mode must be F. 

• Label records must be standard. 

• record contains clause cannot specify 
more than 128 characters, or "integer-1 
to integer-2" CHARACTERS. 

• The BLOCK contains clause must specify 
the records option only. Blocking is 
permitted for the most efficient usage 
of the 3540. If this clause is 
specified, only 1, 2, 13, or 26, will 
be accepted as the blocking factor. 
Any other number will cause a 
diagnostic. 

• In the record description, a maximum of 
128 characters will be allowed for a 
3540 file. 

• The record description for a 3540 file 
must not include any items with the 
OCCURS depending on clause, as variable 
records are not allowed. 



queried to either supply an EXTENT 
through the console or cancel the job, 



Standard errors can be handled in a USE 
AFTER STANDARD ERROR Declarative. Two 
types of errors will cause control to 
return to an error declarative for 3540 
files: 

1 . Data check 

2. Equipment check 

If the GIVING option is specified, byte 

1 will indicate a data check, and byte 

2 will indicate an equipment check. 

In either case, the error procedure is 
used to continue processing or to close 
the file. If processing continues and 
the file is blocked, the remaining 
records in the block after the record 
causing the error may be lost when the 
next READ or WRITE statement is 
executed. 

If no error declarative is specified, a 
message will be issued describing the 
type of error, and the job will be 
canceled. 

CLOSE Statement. When a CLOSE 
statement is executed for a 3540 file, 
the present diskette will be fed out 
into the output hopper. CLOSE UNIT may 
not be used as no forced end-of-volume 
support is included for the 3540 
Diskette unit. CLOSE NO REWIND may not 
be used. The LOCK option will be 
supported for 3540 files. 



Procedure Division — Special 
Considerations 

• OPEN Statement. 3540 files may be 
opened for input or output only . Since 
updating is not permitted for a 3540 
file, OPEN I-O is not allowed. 

• Only one 3540 file per diskette may be 
open simultaneously. 

• The REVERSED and NO REWIND options of 
the OPEN statement are not valid for a 
3540 file. 

• WRITE Statement. The INVALID KEY 
option may not be used for a 3540 file. 
If the end of the diskette is reached 
and additional diskette information has 
not been supplied via additional EXTENT 
control cards, the operator will be 



DTFDU 

The compiler will generate DTFDU with 
the following defaults: 

1 . No write protection 

2. Feed = yes 

3. Volume sequencing will be checked. 

4. No read/write security. 



Job Control Requirements 



Normal job control DLBL and EXTENT 
statements for the 3540 are shown below, 
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DLBL Statement 



The format of the DLBL statement is: 



type — indicates the type of extent. A 
•1* indicates 'data area.* No other types 
are supported. 



// DLBL filename, [ »file-ID»], [date], [code] 

filename — is a unique filename of 3 to 7 
characters identical to the symbolic name 
of the DTF that identifies the file- 
Supported in the same way as for current 
devices. This corresponds to the "name" 
field of system-name in the SELECT 
statement if specified, or to SYSnnn in the 
system-name. 

'file-ID ' — only the first 8 characters 
will be used. Supported in the same manner 
as for current devices. 

date — provides the expiration date for 
the file. Supported in the same way as for 
current devices. 

code — is a field indicating the type of 
file label. DU for diskette unit is 
supported. It is supported in the same way 
as for current devices. 



EXTENT Statement 



The format of the EXTENT statement is: 



3540 File 



The following DLBL and EXTENT statements 
describe a file that resides on a 3540 
diskette. 

// DLBL HASTER,, 75/001, DD 
// EXTENT SYS015, 111111,1 

In the following example, the program 
CREATES creates a diskette (DU) file named 
SALES that is to be retained until the end 
of 1975. The file comprises up to three 
diskettes. The diskettes have the volume 
serial numbers 111111, 111112, and 111113, 
and are mounted on the drive assigned to 
the symbolic device name SYS005. 

// JOB EXAMPLE 

// ASSGN SYS005,X»060» 

// DLBL SALES, 'ANNUAL', 75/365, DU 

// EXTENT SYS005,111111,1 

// EXTENT SYS005, 111112,1 

// EXTENT SYS005, 111113,1 

// EXEC CREATE 

/5 

The COBOL statements which correspond to 
this are: 



i 



// EXTENT [symbolic-unit], 

[serial-number ],[ 1 ] 

symbolic unit — indicates the symbolic 
unit (SYSxxx) of the volume for which the 
extent is effective. It is supported in 
the same way as for current devices. 

serial number — indicates the volume 
serial number of the volume for which this 
extent is effective. It is supported in 
the same way as for other devices. The 
serial number is optional. If omitted, the 
volume that is mounted is assumed to be the 
correct volume. 



SELECT SALES-FILE ASSIGN 

TO SYS005-DA-3540-S-SALES. 



FD SALES -FILE 

RECORDING MODE IS F 

LABEL RECORDS ARE STANDARD 

RECORD CONTAINS 80 CHARACTERS 



01 



DISKETTE-RECORD. 
02 
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VIRTUAL STORAGE ACCESS METHOD (VSRH) 



VSAM is a new access method for direct 
or sequential processing of fixed and 
variable length records on direct-access 
devices. It has more functions, generally 
better performance, better data integrity 
and security, improved data organization, 
and is easier to use and control than the 
D0S/7S BAH and ISAM 3.ccess methods, 

VSAM files can be processed only by the 
VSAH file processing technique. The 
programmer can convert SAM and ISAM files 
to VSAM files by using the method described 
in the section entitled "Converting 
Non-VSAM Files to VSAM Files." The 
following topics related to VSAM are 
discussed in this chapter: 

VSAM File processing 
Access Method Services 
Error Handling 



File Organization 



The records in a VSAM file can be 
organized either in logical sequence by a 
key field (key-sequence) or in the physical 
sequence in which they are written on the 
file (entry-sequence) . 

A key-sequenced file has an index, like 
ISAM; the records in a key-sequenced file 
can be accessed by key, either randomly or 
sequentially. An entry-sequenced file do^es 
not have an index, and records can be 
accessed sequentially only. 



When a key-sequenced file is created, 
certain portions can be left empty, that 
is, free space can be distributed 
throughout the file. This free space is 
used when inserting new records or 
lengthening existing records. This 
eliminates the need for overflow chains 
and overflow areas; it also minimizes 
data movement. Thus performance does 
not degrade substantially as records 
are added and the file does not have to 
be reorganized as often as an ISAM file. 
VSAM reclaims space when a record is 
deleted or shortened, and the space 
released becomes free space. 

The index of a key-sequenced VSAM file 
is more efficient than an ISAM index 
because it generally requires less direct- 
access space and less updating of index 
entries. Space is saved in three ways: 
by eliminating redundant key information 
(key compression) , by having fewer keys 
in the index than there are records in 
the file (non-dense index) , and by 
blocking index records. A shorter index 
requires less time to search and update. 
Updating is infrequent, because index 
entries are not usually modified when 
records are added to or deleted from 
the file. 



A key-sequenced file is defined in COBOL 
by specifying: 

SELECT file-name ASSIGN TO 

SYSnnn[ -class ][ -device ][ -name ] 

ORGANIZATION IS INDEXED 

RECORD KEY IS... 






Key-Seguenced Files 



Like ISAM files, key-sequenced files 
are ordered according to a user-defined key 
field in each record. That 'is, they are 
ordered according to the collating sequence 
of the key field in each record. Each 
record has a unique value in the key field, 
such as employee number or invoice number. 
VSAM uses the key associated with each 
record to insert a new record in the file or 
to retrieve a record from the file. The 
order of access can be random or sequential. 
Key-sequenced files, however, can generally 
be processed faster than ISAM files because 
VSAM has a more efficient index and does 
not use chained record overflow. 



Entrv-Seguenced Files 

Records are stored in entry-sequenced 
files in the order they are presented for 
inclusion on the file (that is, their 
entry-seguence) , and without respect to the 
contents of the records. No keys are 
recognized and, consequently, no indexes 
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are built. The order of records is fixed; 
they are not moved. Thus, free space is 
not distributed throughout the file and new 
records are placed at the end. Records 
cannot be shortened, deleted, or 
lengthened. Since there is no index, the 
user must access the file sequentially (in 
the order the records were written) . 



An entry-sequenced file is defined in 
COBOL by specifying: 



SELECT file-name ASSIGN TO 

SYSnnn[ -class }[ -device ]-AS[ -name ] 
ORGANIZATION IS SEQUENTIAL 



Data Access 



Key sequenced files can be accessed 
either sequentially, or directly by key. 
The key used can be either the full key or 
a generic key (any front part of the full 
key) . 

The COBOL user can retrieve, add, 
update or delete records from a VSAM file 
by means of the READ, WRITE, REWRITE and 
DELETE verbs. Also, by means of the START 
verb he can position himself to any record 
in the file and begin sequential retrieval 
from that record. 



Data Organizatio n 



The data organization of ISAM is based 
on the physical units of disk cylinder and 
disk track, while the data organization of 
VSAM is based on logical uni ts calle d 
control" intervals and cofltroj. area sT A 
control interval is the unit of 
direct-access storage that is transferred 
to and from virtual storage. It can 
contain one or more records in one or more 
blocks. Each entry in the lowest index 
level of a key-sequenced VSAM file points 
to a control interval. Free space in a 
key-sequenced file is distributed in terms 
of the percent of total space. A per- 
centage of each control interval can be 
free space and some control intervals can 
be entirely free space. Indexes are also 
organized in control intervals. Each 
contains a single index record which can 
have many index entries. A control area 
is a group of control intervals. VSAM 
data organization provides for device 
independence by reducing the programmer's 
concern about the physical characteristics 
of the data and the index. Figure 3 5 
illustrates VSAM data and index structure. 



VSAM Catalog 



VSAM keeps central control over the 
creation, access, and deletion of files and 
over the management of direct-access 
storage space allocated to those files. 
This is done by keeping information on file 
and space characteristics in one place, the 
TSAH catalog. The catalog, which is unique 
to VSAM, makes it easier to (1) keep track 
of files and available direct-access 
space, (2) write job control statements to 
create and process VSAM files, and (3) move 
VSAM files to other DOS/VS systems or to 
OS/VS systems. There can be more than one 
VSAM catalog. However, only one catalog 
at a time can be connected to the system. 
Each catalog can keep track of VSAM files 
on many volumes; it is not necessary to 
mount a volume to determine whether or 
not it has space available for a VSAM file. 
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Figure 35 shows the structure of the 
data and index in a VSAM file. It 
does not represent accurate propor- 
tions in terms of the number of 
records in a control interval, etc. 

In the example, if the user wanted to 
add a record whose record key was 1048, 
it logically belongs between records 
1024 and 1068. This is where VSAM 
would insert the record physically. 
The record with key 1068 would be 
moved over in the control interval 
taking up free space, to make room 
for the new record. This movement 
of records is done in core before any 
writing takes place. 

This example illustrates several 
points: 



1) New records are physically 
inserted where they logically 
belong with only local record 
movement required. Thus, new 
records are retrieved in the 
same fashion as are old records 

2) Since the index pointers are 
non-dense (one for each control 
interval rather than one for 
each record) , the insertion of 
tiie record requires no change 
to the index. 

3) Record movement for insertion, 
deletion and updating takes 
place in core, before any I/O 
takes place, thus improving 
data integrity. 
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Figure 35, VSAH Data Organization 
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File and Volume Portability 



A significant feature of VSAM is that 
files can be moved from one DOS/VS system 
to another o;r to an OS/VS system. This 
is possible because VSAM. data format is 
identical under both DOS/VS and OS/VS. 



tne operator and/or programmer. These are 
listed in "Appendix I: Diagnostic 
Messages ." 

For more detail on VSAH, refer to DOS/VS 
Access Method Services. 



ACCESS METHOD SERVICES 



Service Programs 



VSAH has an extensive service program 
package, called Access Method Services, 
which can be used to: 



• Define, print, copy , or 
reorganize VSAM files. 

• Add, alter, delete, or print catalog 
entries. 

• Convert ISAM and SAM files to VSAM 
files. 

• Export and import files from one 
system to another. 

Device Support 



VSAM files can be written on 2314, 3330, 
3340, 3350, and fixed block devices. 



Security 



Through COBOL, access to the file can be 
restricted by use of the PASSWORD clause in 
the SELECT statement. 

Error Processing 



VSAH provides exits to a user-supplied 
routine to handle I/O and/or logical errors 
or exeception conditions. This is done in 
COBOL via the USE AFTER STANDARD ERROR 
declarative and the INVALID KEY and AT END 
clauses. A STATUS KEY may be specified, 
and the details of the condition 
determined. 

VSAM Messages 



Like other access methods, VSAM issues 
messages to the operator, if for example, 
the incorrect volume is mounted, etc. 
These messages are described in DOS/VS 
Messages . VSAH Access Method Services also 
issues messages to the programmer which are 
documented in DOS/VS Access Method 
Services. COBOL issues VSAM messages to 



Access Method Services is a utility 
program. A number of user-entered 
commands, either modal or functional, 
initiate the Access Method Services 
programs . The functional commands 
invoke the desired Access Method 
Services function while the modal 
commands control the sequence of exe- 
cution of the functional commands. In 
this chapter, only certain commands 
and parameters are discussed. For 
complete details on the use of 
commands see DOS/VS Utilities Access 
Method Services . 



Functional Commands 



There are nine functional commands: 
DEFINE, ALTER, DELETE, LISTCAT, REPRO, 
PRINT, IMPORT, EXPORT, and VERIFY. The 
commands DEFINE, ALTER, and DELETE are 
used to create, modify, and remove VSAM 
catalogs and files. LISTCAT is used to 
list the contents of a VSAM catalog. 
The REPRO and PRINT commands reproduce 
files either as new files or as printed 
output. The IMPORT and EXPORT commands 
provide for transfers of files from one 
system to another. The VERIFY command 
provides a file recovery service for' 
VSAM files by ensuring that the end of 
the file indicated in the catalog is 
the same as the actual file end. 



The DEFINE Command 



All VSAM files must be cataloged in a 
VSAM catalog. This catalog must be defined 
and allocated by Access Method Services. This 
is the first step which must be taken by a 
user who plans to use VSAM. 

The DEFINE command is used to define a 
VSAM object. In VSAM terminology, an object 
is either a VSAM catalog, a VSAM data space, 



i 
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VSAM files must be cataloged in a VSAM 
catalog. Non-VSAM files may also be cata- 
loged in a VSAM catalog. All VSAM files 
are introduced to the system through the 
DEFINE command. 



There are two steps in the creation of 
an object: defining the object in the 
catalog, and generating the contents of 
that object. The DEFINE command sim.ply 
makes an entry in the catalog, it does not 
generate any content. 



The following is an example of defining 
a VSAM master catalog. 



Specification of the DEFINE Command 



Format 



DEFINE object parameters 



The definable objects are: 

• MASTERCATALOG — specifies that the 
VSAH master catalog is to be defined. 

• SPACE — specifies that a VSAM data 
space is to be defined, 

• CLUSTER — specifies that a file is to 
be defined. 

For each file there is an associated 
valid parameter list. 



Defining a VSAM Master Catalog: DEFINE 
MASTERCATALOG 



The DEFINE MASTERCATALOG command must 
be used to set up the master catalog. It 
is the first Access Method Services com- 
mand used since without a master catalog 
other objects cannot be defined. Defining 
a master catalog is somewhat different 
from defining a file. When the user de- 
fines a file he need not necessarily allo- 
cate space as part of the define operation, 
However,- the process of defining catalog 
always involves the allocation of space 
for that catalog. Entries for both the 
master catalog itself and the volume con- 
taining the data space automatically 
created are placed in the master catalog. 



I// JOB 
I// DLBL 
I// EXTENT 
I// EXEC 
I DEFINE 



I/* 
l/S 



DEFINE A VSAM CATALOG 

IJSYSCT,'VSAaCAT»,,VSAM 

SYSCAT, 32 1940,1,, 100, 250 

IDCAKS,SIZE=26K 

MASTERCATALOG (NAME (VSAMCAT) " 

VOLOME (321940) TRACKS (250) - 

FILE (IJSYSCT) DPDATEPW (SECRET) - 

READPW{NOSECRET)) 



Figure 36. Defining a VSAM Master Catalog 

The DLBL statement must be used to 
specify the filename and the code which 
identifies VSAM. The filename must be 
specified as IJSYSCT. 

The logical unit in the EXTENT statement 
must be SYSCAT. The user must decide which 
volumes and which extents will contain the 
catalog. Note that the VOLUMES parameter 
and the space allocation parameter 
(CYLINDERS, TRACKS, or RECORDS) must be 
included in the DEFINE command, and must 
agree with the information in the EXTENT 
statement. If the CYLINDERS parameter is 
used, each extent must begin on a cylinder 
boundary. 

The following parameters were used in 
the above example: 

NAME (VSAMCAT) 

The name of the VSAM master catalog 
is VSAMCAT. All future references to 
the catalog are made using this name. 

VOLUME (321940) 

The volxime serial number on which the 
catalog is to reside is 321940. 

TRACKS (250). 

The number of tracks allocated to the 
catalog is 250. This must agree with 
the information on the EXTENT card. 

Note that every key-sequenced file 
requires three catalog entries: one 
each for the cluster, data component, 
and index component. Every 
entry-sequenced file requires two 
catalog entries: one for the cluster 
and one for the data component. 

FILE (IJSYSCT) 

This parameter identifies the 
filename of the DLBL statement 
that specifies the device and 
volume for allocation. The 
filename must be specified as 
IJSYSCT. 
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UPDZ\TEPV7 (SECRET) 

The update level password is SECRET. 
This is an optional parameter. 
However, if any file which is 
cataloged in the VSAI/I catalog is to 
be password protected, the catalog 
itself must also be password 
protected. 

READPW (NOSECRET) 

The read level password is NOSECRET. 
This is an optional parameter. If 
specified, all reading of the catalog 
requires this password. 

There are 4 levels of password pro- 
tection for a VSAM catalog or file. They 
are: master level (this is the highest 
level of protection) , the CI level (this is 
a special case and should not be used with 
COBOL) , the update level and the read level 
(the lowest level of protection) . 

If password protection is not speci- 
fied at a higher level, but is specified at 
a lower level, then the lower level pass- 
word becomes the password for the higher 
levels which are not specified. If 
password protection is not specified for 
the lowest level (read level) then there is 
no password protection for that lowest 
level or for the higher levels which 
are not specified. 

So in the example, SECRET is the mas- 
ter level password as well as the update 
level password, since the master level 
password was not specified. 

The update level password of the 
catalog is required in order to change 
the content of the catalog, for example to 
DEFINE or DELETE a file in that catalog. 



Figure 37 is an example of defining a 
VSAM data space: 



Defining a VSAM Data Space: DEFINE SPACE 

VSAI4 data space is space which is 
owned and managed by VSAM. When space on 
volume is defined in a VSAM catalog then 
that volume is said to be owned by that 
VSAM catalog. This means that no other 
VSAM catalog can own space on that volume. 
It does not mean that there can be no 
non-VSMI space on the volume. 

VSAM data space can contain the 
records for one file or for many files, 
but all the files occupying a VSAM data 
space must be cataloged in the same VSAM 
catalog as is the space. 

Since the process of defining VSAM 
data space necessarily requires the allo- 
cation' of space, JCL is required for ex- 
tent information. 



I// JOB 
I// ASSGN 
I// DL3L 
I// EXTENT 
I// EXEC 
I DEFINE 
I 



I/* 



DEFINE A VSAM DATA SPACE 

SyS001,X'13O' 

VFILENM,, ,VSAM 

SYSOO 1,32 1942,1,, 800, 400 

IDCAMS,SIZE=26K 

SPACE (FILE(VFILENM) 

TRACKS (400) 

VOLUMES (321942)) 

CATALOG (VSAMCAT/SECRET) 



Figure 37. Defining a VSAM Data Space 



Tlie DLBL statement must be used to 
specify the filename and the code which 
identifies VSAM files. The filename 
(VFILENM) is the same as the FILE parameter 
and connects the job control statements to 
the DEFINE command. The EXTENT statement 
must be used to specify the symbolic unit 
name, the volume serial number, and the 
space parameters. The VOLUMES parameter 
and the space allocation parameter 
(CYLINDERS, TRACKS, or RECORDS) must be 
included in the DEFINE command, and must 
agree with the information in the EXTENT 
statements. If the CYLINDERS parameter is 
used, each. extent must begin on a cylinder 
boundary. 



The following parameters were used in 
Figure 37. 

FILE (VFILENM) 

This required parameter identifies the 
filename of a DLBL statement that 
specifies the devices and volumes to 
be used for space allocation. 

TRACKS (40D) 

This parameter specifies the amount 
of space to be allocated in terms of 
tracks. The number used to specify 
the tracks to be allocated to the 
data space must agree with the 
information in the extent statements. 

VOLUMES (321942) 

This required parameter specifies the 
volumes to contain the data spaces. 
If more than one volume is specified, 
each volume will contain a data space 
of the same size. Note that the 
VOLUMES parameter must agree with the 
information in the EXTENT statements. 
The volume serial number of the 
volume (s) containing the data space (s) 
is substituted for volser. 
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CATALOG (VSAMCAT/SECRET) 

This is a required parameter if the 
master catalog is password protected. 
It specifies the name of the catalog 
which is to own the space, and the 
update password for that catalog. 



VOLUME (231942) — This required 
parameter is used to specify the 
volume on which the defined object is 
to be placed. 

RECORDS (primary [secondary] ) — This 
parameter specifies the amount of 
space to be suballocated in terms of 
the number of records the space is to 
hold. 



Definina a VSAM File: DEFINE CLUSTER 



DEFINE CLUSTER is used to define all 
attributes of all VSAM files and to catalog 
the files in a VSi^M catalog. 

Note: This command cannot be used to add 
records to the VSAM file. 

VSAIl files can be sub-allocated or 
unique. A sub-allocated file is one which 
is defined using space from one or more 
existing data spaces. For such a file, DLBL 
and EXTENT statements are not required. 
Label processing is not performed since 
information needed to set up the file is in 
the DEFINE command, and information about 
the data spaces to be used for the file is 
in the VSA!5 catalog. 

A unique VSATl file is one which 
occupies data space uniquely allocated 
to it, not to be shared by other files. 
The data and the index of a key- 
sequenced unique file must occupy 
separate data spaces; each requires 
DLBL and EXTENT statements. 



Figure 38 is an example of defining a 
suballocated key-sequenced file. 



// JOB DEFINE 

// EXEC IDCAMS,SI2E=26K 

DEFINE CLUSTER (NAME (HSTRFILE) 
RECORDS (100,10) 
VOLUME (231942) 

RECOEDSIZE(40 55) 
FESESPACE(10 5) 

SUBALLOCATION - 
INDEXED - 
KEYS {8 2) UPDATEPW (WRITEFL) - 
ATTEMPTS (0) ) 

CATALOG (VSAMCAT/SECRET) 

I 

Figure 38. Defining a Key-Sequenced 
Suballocated VSAa File 

The following parameters are used in 
Figure 38. 

• NAME (MSTRFILE) — This parameter is 
required and specifies the name to be 
given to the file being defined. 



RECORDSIZE (sizel size2) — This 
required parameter specifies the length 
attributes of the logical records in 
the file. The size specified can be 
from 1 to 32,761. sizel is the average 
length of all logical records. size2 
is the maximum length of any logical 
record . 



FREESPACE (percent 1 [percent 2]) — 
This parameter specifies the percen- 
tage of space that is to be reserved 
during initial and subsequent alloca- 
tions, percent 1 specifies the amount 
of unused space to be left in each 
control interval. percent 2 specifies 
the amount of unused control intervals 
be left in each control area. 



Note : This parameter is valid for 
key-sequenced files only. 



DNIOUE/SUBALLOCATION — This parameter 
specifies whether the object is 
allocated a space of its own, or 
whether a portion of an already defined 
VSAK data space is suballocated to the 
object. 



UNIQUE 

specifies that the object being 
defined is allocated a space of its 
own. An object with the UNIQUE 
attribute appears in the VTOC of 
its volume under its own name. 



SUBALLOCATION 

specifies that a portion of an 
already defined VSAK data space is 
suballocated to the object. Objects 
with the SUBALLOCATION attribute do 
not appear in the VTOC. Only the 
name of the data space that 
contains the object appears there. 
If the object has the SUBALLOCATION 
attribute, there must be a VSAM 
data space defined on the volume on 
which the object is being defined. 
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INDEXED/NONTNDEXED — This parameter 
specifies the type of cluster being 
defined. 

INDEXED 

specifies that the cluster being 
defined is for a key-seguenced 
file. This is the default. 

NONINDEXED 

specifies that the cluster being 
defined is for an entry-seauenced 
f ile . 

KEYS (length position) — This i 
parameter specifies the length and the 
starting position of the key field 
within each logical record. (Position 
is the first byte in the logical 
record.) The key field with this 
specified length, and starting in the 
specified position, is in all logical 
records in a key-seguenced file. The 
sum of length and position must be 
equal to or less than the length of the 
logical record. 



Entry-Seguenced File Processing : An 
entry-seguenced file can only be processed 
sequentially; therefore, since the default 
is sequential, the ACCESS clause need not 
be specified. 

Key-Seauenced File Processi ng : A 
key-sequenced file can be processed 
sequentially, randomly, or both 
sequentially and randomly. To process 
sequentially, ACCESS IS SEQUENTIAL is 
specified. To process randomly, ACCESS IS 
RANDOM is specified. To process both 
sequentially and randomly, ACCESS IS 
DYNAMIC is specified. 

ACCESS IS DYNAMIC provides the greatest 
flexibility since all the capabilities of 
both sequential and random processing are 

supported. Processing can be switched 
from sequential to random and vice-versa, 
as many times as desired. 



Current Record Pointer 



UPDATEPW (password) — This parameter 
specifies the update level password 
for the file being defined. The 
update level password permits input 
and output operations (READ, START, 
DELETE, WRITE, REWRITE) against the 
logical records of the file. 



Note that this file has no read-level 
protection and that its master level 
password is WRITEFL. 

ATTEMPTS (count) 

specifies the maxiaum number of 
times the operator can try to enter 
the password in response to a 
prompting message. Count can be 
any number from through 7. The 
value prevents any password 
prompting. 



CATALOG (catalog name/password) 

specifies the catalog and its update 
level password that is to contain the 
entries for the cluster. 



The current record pointer (CRP) , a 
conceptual pointer, is applicable only to 
key-sequenced files. The current record 
pointer indicates the next record to be 
accessed by a sequential request; the CRP 
has no meaning for random processing. The 
CRP is affected only by the OPEN, START and 
READ statements, it is not used or affected 
by the WRITE, REWRITE, or DELETE 
statements. The following are examples of 
how the CRP is affected by various COBOL 
statements. 



Example 1 : 

Assuming a file has records with keys 
from 1 to 10, if the sequence of I/O 
operations on the file with ACCESS IS 



DYNAMIC and opened I-O is 



MOVE 7 TO RECORD-KEY 

READ filename 

MOVE 'I a TO RECORD -KEY 

WRITE record -name 

READ filename NEXT RECORD 



File Processing Techniques 



The COBOL user has three different file 
processing techniques available to him; 
sequential, random, and a combination of 
sequential and random. The technique to be 
used is specified through the ACCESS clause 
of the SELECT statement. 



the BEAD NEXT reads record 8 if the 
previous READ was successful. If the 
previous READ was not successful, the 
STATUS KEY will be set to 94 (No Current 
Record Pointer) when the READ NEXT is 
attempted. This occurs independently of 
the successful intervening WRITE. 
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Generally, the last request on a file 
which establishes a CRP (OPEN, READ, or 
START) must have been successful in order 
for a sequential read to be successful. 



Example 2 : 



In this example, ACCESS IS SEQUENTIAL is 
specified; therefore, records are retrieved 
in ascending key sequence starting at the 
position indicated by the CRP, (Assume 
this file has records with keys from 1 to 
10.) 



OPEN INPUT filename 

MOVE 10 TO RECORD-KEY 
START filename 

READ filename 

MOVE 5 TO RECORD- KEY 
START filename 

READ filename 
READ filename 



(CRP is at first 
record on the 
file) 



(CRP is now at 
record 10) 

(record 1 is 
read) 



(CRP is now at 
record 5) 

(record 5 is read 
CRP is set to 
record 6) 

(record 6 is read 
CRP is set to 
record 7) 



Note that the CRP can be changed randomly 
through the use of the START statement. 
All reading is then done sequentially from 
that point. In this example, if the START 
request for record key 5 had failed with 
no record found (File Status=23) , the 
three READ statements following would have 
failed with no current record pointer 
(File Status=94) . 



Example 3 : 



In this example ACCESS IS DYNAMIC is 
specified. Therefore, records are accessed 
randomly if READ is specified and 
sequentially if READ NEXT is specified. 
(Assume this file has records with keys 
from 1 to 44.) 



OPEN INPUT 

MOVE 5 TO RECORD-KEY 
READ filename 



READ filename 
NEXT RECORD 
(or indent a couple 
of spaces) 

Move 41 TO PECORD-KEY 

READ filename 
NEXT RECORD 
(or indent a couple 
of spaces) 



(CRP is set to first 
record on file) 



(record 5 is read, CRP 
is set to record 6) 

(record 6 is read, CRP 
is set to record 7) 



(record 7 is read, CRP 
is set to record 8) 



The last READ NEXT RECORD does not read 

record 41 even though the record key field 
contained 41 . This is true because a 
sequential read does not use the contents 
of the record key to determine which record 
to read, it uses the position of CRP as 
established by a previous request. If the 
last READ had been a random read (no NEXT) 
then record 41 would have been read. 

Example 4 : 

In this updating example, ACCESS IS 
DYNAMIC is specified; the REWRITE statement 
does not affect the CRP. (Assume this file 
has records with keys from 1 to 44.) 






OPEN I-O 



MOVE 10 TO RECORD-KEY 



READ filename 



(CRP is at first 
record on file) 



(record 10 is read, 
CRP is set at record 
11) 



MOVE 44 TO RECORD-KEY 

REWRITE record-name (record 44 is updated, 

CRP is set at record 11) 



READ filename 
!S[EXT RECORD 

MOVE 74 TO RECORD-KEY 

REWRITE 

READ NEXT 



(record 11 is read, CRP 
is set at record 12) 



(fails, record not 
found in this file) 

(record 12 is read, 
CRP is set at record 13) 



Note that although the last REWRITE failed, 
the following READ NEXT was successful. 
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Table 11- File Status Values and Error Handlino 



First Character 
of FILE STATUS 



No USE Declarative 

1 



AT END or INVALID 
KEY clause 



Return to next 
sentence 



No AT END or 
INVALID KEY 
clause 



Return to next 
sentence 



USE Declarative 



AT END or INVALID 
KEY clause 



Return to next 
sentence 



No AT END or 
INVALID KEY 
clause 



Return to next 
sentence 



Return to AT END 
address 



Return to next 
sentence 



Return to AT END 
address 



Return to next 
sentence after USE 
declarative is 
executed 



Return to INVALID 
KEY address 



Return to next 
sentence 



Return to INVALID 
KEY address 



Return to next 
sentence after USE 
decla;rative is 
executed 



Write message and 
return to next 
sentence 



Write message 
and return to 
next sentence 



Return to next 
sentence after USE 
declarative is 
executed 



Return to next 
sentence after USE 
declarative is 
executed 



Return to next 
sentence 



Return to next 
sentence 



Return to next 
sentence after USE 
declarative is 
executed 



Return to next 
sentence after USE 
declarative is 
executed 



ERROR HANDLING 



Record Formats for VSAH Files 



All errors on a VSAH file, whether logic 
errors caused by the COBOL programmer (for 
example, reading an unopened file) , or I-O 
errors on the external storage media, 
return control to the COBOL program. The 
contents of FILE STATUS indicate the status 
of the last request on the file. It is 
strongly recommended that all files have a 
file status associated with them, and that 
the COBOL programmer check the contents of 
FILE STATUS after each request. 



Table 11 describes the actions taken for 
all the combinations of AT END, INVALID 
KEY, and error declaratives for each value 
of FILE STATUS. 



Note: Return is always to NEXT STATEMENT 
unless the request that caused the error 
contained an AT END or INVALID KEY clause. 
By omitting both the AT END and INVALID KEY 
clauses and the USE ERROR/EXCEPTION for the 
file, any type of error for the file can be 
intercepted by checking the FILE STATUS 
data name following each I/O request 
(including OPEN and CLOSE) for the file. 
This will simplify the exception-condition 
handling in the COBOL program. 



For VSAM files, processing is 
independent of whether or not the records 

on a file are fixed-length (that is, all 
records in the file are the same length) 
or of variable- length format. 



Thus for example, the considerations 
which are discussed in "Record Formats For 
Non-VSAM Files" generally do not apply. 



However, the following points should 
be considered: 

• For record handling purposes, the 
records are considered to be 
fixed-length when 

1 . All the records in the file are the 
same size (or there is only one 
record description) . 

2. No record contains an OCCURS clause 
with the DEPENDING ON option. 

Otherwise, the records are 
considered to be variable length. 

• For variable length records, without 
OCCURS DEPENDING ON clauses, the 
following applies: 



1 
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When a READ INTO stateirent is used, the 
size of the longest record for the file 
is moved to the input area. Coding 
considerations for records with the 
OCCURS DEPENDING ON option are 
discussed in "Table Handling 
Considerations . " 

Initial Loading of Records into a File 



A non-loaded file is one which has 
been defined but has never contained 
any records. An unloaded file is one 
which has contained records but from 
which all records have been deleted. 
A loaded file is one which contains 
records. 



File Status Initialization 



The value of "Z' in Status Key 1 is 
reserved for the programmer's use. This 
permits his determining whether a request 
was made against his file. For example, if 
he initializes Status Key 1 to the value Z 
before attempting to OPEN his file he can 
then determine if his program actually 
attempted the OPEN by checking the contents 
of Status Key 1. If it is Z, the OPEN 
statement was not executed; if it is a 
value other than Z„ the statement was 
executed. This same technique can be used 
for any request against the file (CLOSE, 
READ, etc.) to determine if such a request 
was attempted in his program. 



Initial loading is the process of 
writing records into a non-loaded file. 

It is stroiigly ^ recommended that ini tial 
lo a3Tag of r^ecorSs into a~ key- sequ enced 
-TiTe be done sequentially. lf-i;^TS initia l 
^ loading is done randomly, performance vJ^il l 
be slower, not only for the init ial loadin g 
pr ocess, but also for all processing do ne" 
""oh'that file later on. Random loading of 



records does not reserve free space in the 
file; therefore, the file will be 
dynamically reorganized when any subsequent 
records are inserted. 

The following table illustrates which OPEN 
options are allowed for each file state. 



FILE 
\ .STA.TE 



OPEN 
OPTION 



iNON- LOADED UNLOADED LOADED 



1 








INPUT 


NO 


YES 


YES 1 


OUTPUT 


YES 


NO 


NO j 


I-O 


NO 


YES 


YES ] 


EXTEND 


YES 


YES 


YES 1 

1 



From this table it can be seen that opening 
a file with the OUTPUT option is valid only 
when the file is new (has never contained 
any records). Also, opening a file with 
the INPUT or 1-0 option is valid only when 
the file is not new. If such a file 
contains no records (is in the unloaded 
state) the first READ request results in 
an AT END condition (if ACCESS IS 
SEQUENTIAL) or an INVALID KEY condition 
(if ACCESS IS RANDOM or DYNAMIC) . 



Opening a VSAM File 



If any of these rules are violated, the 
file is not opened and the FILE STATUS key 
is set to the appropriate value. Refer to 
Table 12 for FILE STATUS key values at open 
time. Table 13 describes file status at 
action request time. 

A loaded file can be opened EXTEND, 
INPUT, or I-O. If such a file is 
opened EXTEND and it is a key-sequenced 
file, the first record to be added must 
have its record key higher than the 
highest record key on the file when 
it was opened. If it is not higher, a 
logic error results, and the FILE 
STATUS key is equal to 92. For an 
entry-sequenced file, the records are 
.added after the last record. 

Since the USE declarative is executed 
only for files that are in open status, the 
only OPEN error which can cause the USE 
DECLARATIVE to be invoked is trying to open 
a file which is already in the open status. 
This is a logic error and causes file 
status to be set to 92. The open status of 
the file is not affected. However, if the 
file is defined as ACCESS IS DYNAMIC, the 
illegal OPEN statement causes the current 
record pointer to be undefined. 
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H niAXVL iMJL (tilJ^'^^^^^^sIL 

Table 12. File Status Key Values at OPEN 



6,^<J 



/i 



r T- 

File Status 1 

i-- 



Probable Cause 



30 



I-O error 



91 



j Incorrect password. Either an incorrect password was specified or a 
I required password was not specified. If a file is opened OUTPUT, 
I EXTEND, or I-O, the UPDATE password is required. 



92 



Logic error caused by opening an opened file, or by opening a locked 
file. 



93 j Resource not available. Caused by insufficient virtual storage, or the 

j file is not available for the type of processing requested.^ 
4. 

95 I Invalid or incomplete information in the ASSGN card, or the file was not 
I found in the catalog. ^ 



96 



I Missing DLBL card 
-i 



^Indicates that the file was already opened by someone else and opening it for this 
request would violate the share options specified for the file. 

2FILE STATUS 95 can also be caused by the following: 

- an attempt to open a key-sequenced file as if it were an entry-sequenced file or 
vice versa. 

- an attempt to open a non-loaded file with the INPUT or I-O option. 

- an attempt to open OUTPUT a file not in the non-loaded state. 

- record key length or displacement specification that does not match what was 
specified when the file was defined. 



Table 13. File Status at Action Request Time 



File Status 



Probable Cause 



00 
10 
21 

22 
23 

24 

30 
34 

92 
93 

94 
99 
138 



key-sequenced] 
file only 



Successful 

A sequential READ statement encountered EOF. 

A request was issued to change the record key during execution of 
a REWRITE statement, or a sequence error occurred for a 
sequentially-accessed key-sequenced file. 

A request was issued to add a record whose record key was a 
duplicate of a record already on the file. 

Either a READ_statemeni__was issued for a record whose record^^Jtey 
3o^s;^^EIfflatch_3j^t»j«icQE^^ 
statement was issued for arecord'^not on the file. 



A requesr~was issued to write a record "BeySiTijnSRe 
externally-defined boundaries of the file. 

An I-O error occurred. 

A request was issued to write a record beycnd the 
externally-defined boundaries of an entry-sequenced file. 



A logic error occurred. 



(See Note below.) 



Resource not available. Insufficient virtual storage or volume, 
extent unavailable, or data already in exclusive control. 

No current record pointer for a sequential READ statem.ent. 
Abnormal termination (subroutine error) . 



Note : File Status = 92 can be caused by 
the following: 

• Any request issued against an unopened 
file. 

• Any request issued which is not allowed 
for the OPEN option; for example, 
issuing a READ statement for a file 
opened OUTPDT, or a REWRITE statement 
for a file opened INPUT. 



• Any attempt to write or rewrite a 
record longer than the maxiisum record | 

I size specified when the file was / 
V defined. y 

• Any action taken on a file after EOF 
has been encountered (entry-sequenced 
or key-seguenced file) . If EOF is 
encountered on a key-seguenced file, a 
START or a READ statement can be issued 
to reset the CRP and continue 
processing. For example, a 
key-sequenced file with ACCESS IS 
SEQUENTIAL specified: 






OPEN 

READ 

READ 

READ 

START 

READ 



successful 
EOF encountered 
logic error 
reset CRP 
successful 



or, a key-sequenced file with ACCESS IS 
DYNAMIC specified: 



OPEN 

read next 
read next„ 
read'^neTt 

READ 
READ NEXT 



successful 
,„EOF^.ensaJiiLter;ed 
logic error 

reset CRP {random. READ) 
successful 



• An attempt to rewrite when ACCESS IS 
SEQUENTIAL has been specified if the 
preceding action was not a successful 
READ operation. 

• An attempt to delete when ACCESS IS 
SEQUENTIAL was specified if the 
preceding action was not a successful 
READ operation (key-sequenced file 
only) . 

• An attempt to read with improper 
length specified. 



WRITING RECORDS INTO A VSAH FILE 



The COBOL WRITE statement is used to add 
a record to a file. {Existing records in 
the file are not replaced with this 
statement.; The record to be written must 
wot be larger than the maximum record size 
specified when the file was defined. 



Entry-Seguenced File Considerations for the 
WRITE Statement 

Entry-sequenced file records are 
written sequentially. If the file 
is not opened OUTPUT or EXTEND, FILE 
STATUS is set to 92 and the record 
is not written. 



Key-Sequenced File Considerations for the 
WRITE Statement 



When ACCESS IS SEQUENTIAL is specified, 
the file must be opened OUTPDT or EXTEND. 
If not, the WRITE statement is not executed 
and FILE STATUS is set to 92. 

The records must be written in ascending 
key sequence. If the file is opened 
EXTEND, the record keys of the records to 
be added must be higher than the highest 
record key on the file when it was opened. 
The following example shows the action and 
resultant FILE STATUS when a file 
containing records whose keys are 2, 4, 6, 
8, and 10 is opened EXTEND. (Refer to 
Table 13 explanations of FILE STATUS values 
at action request time.) 

ACTION FILE STATUS 
WRITE (record key =8) S2 
V7RITE (record key =9) 92 
V7RITE (record key =12) 00 
WRITE (record key =11) 21 
WRITE (record key =6) 21 

Note that the first tv/o WRITE re'^uests 
result in a logic error (FILE STATUS=92) 
because their key values are not higher 
than the highest key on the file when 
it was opened. Once a successful WRITE 
has taken place all subsequent WRITE 
requests are handled as though the file 
were opened OUTPUT. This is why the 
WRITE of record key 6 causes a sequence 
error, not a logic error. 



_If many__Xfecords are to be added to a 
fj-lej^rfis strongly recommended that 
h^§;^§^J^^J.''''^cc.^ss.^ be used. Performance is 
improved "both for the process of adding t'he 
records and "T6F later retrieval of them. 

When ACCESS IS RANDOH or ACCESS I S 
DYNAMIC is specified/ thp~file miist"^be 
opened I-O or OUTPUT. If not, the WRITE 
bid Lament is not executed and FILE STATUS 
is set to 92 . The records can be written 
in any order. 
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BEWRITING RECORDS ON A VSAH FILE 

The COBOL REWRITE statement is used to 
replace existing records on the file. 

Entry -Sequenced File Considerations for the 
REWRITE Statement 

For successful REWRITE statement 
execution, the file must be opened I-O. 
The record to be rewritten must first be 
read by the COBOL program, then updated by 
the REWRITE statement. (The length of the 
record being rewritten cannot be changed.) 
If there was no preceding READ statement, 
or if the preceding READ statement was not 
successful (EOF was_rsa,^Jjedj , the REWRITE 
statement is jiot' executed aTfiu^'^Pfl^j;, STATUS 

is-set- 'to -9'2T ""^"^x 

■L X 

\ Key-Sequenced File Considerations for the \ 

IreWRITE statement 



successful and unsuccessful READ and START 
executions. (Assume this file has records 
with keys 1 through 8 and 20.) 



OPEN 1-0 
filename 

READ 

file name 

M.OVE 10 TO 
RECORD-KEY 

START 

file name 

READ 

file name 

MOVE 20 TO 
\ RECORD- KEY 



CRP at first record on 
file 

(first record on file is 
read) 



(fails-no record found; 



(fails-no CRP) 



; For successful REWRITE statement 
execution, the file must be opened I-O. 
The length of the record can be changed, 
but the value of the record key cannot be 
changed. 

When ACCESS IS SEQUENTIAL is specified, 
the record to be rewritten must first be 
read by the COBOL program, then updated by 
the REWRITE statement. The REWRITE 
statement is not successful if the 
preceding statement for the file was not a 
successful READ of this record. This 
causes file status to be set to 92. 

When ACCESS IS RANDOM or ACCESS IS 
DYNAMIC is specified, the record does not 
need to be read by the COBOL program. The 
record is updated by moving its key to 

the record key field and doing the REWRITE. 

READING RECORDS oli^A'TSAii. ,.EIJ,£„ „_,_ 

The COBOL READ statement is used to 
access records on a file. If the file is 
not opened INPUT or I-O, the READ statement 
is not executed and FILE STATUS is set to 
92. 



START (successful) 
file name 

llEAD (record 20 is read) 

file name 



I When ACCESS IS RANDOM is specified, 
jrecords are read in the order specified by 
the program. To read records whose record 
key is 10, move 10 to the RECORD KEY field 

in the record area and issue a READ 
statement. 

When ACCESS IS DYNAMIC is specified, 
records can be read randomly or 
seguentially. The READ NEXT statement is 
used for sequential accessing, and the READ 
statement is used for random accessing. 



READ NEXT Statement 



Entry-Sequenced File Considerations for the 
READ Statement 

Records are read seguentially, in the 
order in which they were written. 

Key-Sequenced File Considerations for the 
READ Statement 



Records are read seguentially beginning 
at the position of the current record 
pointer. If the current record pointer is 
not defined when the READ NEXT statement is 

issued, FILE STATUS is set to 94 as a result 
of the READ. The current record pointer is 
considered undefined if the preceding START 
or READ statement was not successful. 



When ACCESS IS SEQUENTIAL is specified, 
records are read sequentially, beginning at 
the position of the current record pointer. 
If the current record pointer is undefined 
when the READ is executed, FILE STATUS is 
set to 94. The following example shows 



For details on the effect of COBOL 
statements on the position on the current 
record pointer, refer to the section 
entitled "Current Record Pointer." 
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READ Statement 



COBOL Language Usage With YSAH 



The READ statement reads records 
randomly using the value placed in the 
record key field. 



USING THE START VERB 



ilid for 

I key-seguenced files but not when ACCESS IS 
I RANDOM is specified or when the file is 
1 opened OUTPUT or EXTEND. 

In some of the preceding examples, the 
START verb was used to position the CRP. 
Then the READ (for ACCESS IS SEQUENTIAL) 
and READ NEXT (for sequential processing 
when ACCESS IS DYNAMIC) retrieves the 
record pointed to by the CRP as established 
by the START. 



Example: 



05 



RECORD-KEY. 

10 GENII. 

15 GEN12 PIC 99, 
15 GEN13 PIC 99. 

10 GEN14 PIC9. 



In this example, GEN 12, GENII, or 
RECORD-KEY could be used as the data-name 
in the "KEY IS relational data-name" option 
of the START statement. The lengths would 
be 2, 4, and 5 respectively. GEN 13 and 
GEN 14 could not be used as they are not in 
the leftmost part of RECORD-KEY. 

Assume that the value of RECORD-KEY is 
01472: 

• START filename KEY = GENII would 
position the CRP to the first record on 

the file whose key has 0147 as the 
first 4 characters. 

• START file-name KEY > GEN12 would 
position the CRP to the first record in 
the file whose key has the first two 

characters greater than 01 . 



DELETE Statement 



The DELETE is valid only for a 
key-seguenced File. The same 
considerations discussed under 
"Key -Sequenced File Considerations for the 
REWRITE Statement" apply to the DELETE 
statement. 



The COBOL language statements which are 
directly related to VSAM processing are in 
the section "DOS/VS COBOL Considerations" 
in the publication IBM DOS Full American 
National Standard COBOL . The following 
paragraphs are intended only to highlight 
and summarize the basic language statements 
used in writing a VSAM-f ile-processing 
COBOL program. 

A COBOL prograinTner can use VSAI-^. in three 
basic ways: to create a file, to retrieve 
a file, and to update a file. However, 
prior to processing a VSAM file, it is an 
absolute necessity that the previously 
discussed Access Method Services functions 
be performed. Most significant to the 
COBOL programmer is whether the file is 
defined as an entry-seguenced file or as a 
key -sequenced file. 

Creating a YSAH File 

The minimum COBOL language statements 
required to create a VSAM file are 
summarized in Table 14. 

Table 14. COBOL Statements for Creating a 
VSAM File 






1 - ■ ' 


■ i 1 
i 1 1 
1 Entry-Seguenced | Key-Seguenced | 




1 File 
1 


( File 1 
1 1 


1 Environment 


1 SELECT 


1 - ■ ■ 1 

[SELECT 1 


1 Division 


[ASSIGN 

1 

i 

1 
1 


{ASSIGN 1 

[ORGANIZATION | 

{ IS INDEXED 1 

[RECORD KEY { 
1 t 


IData 


|FD entry 


_ ^ 1 

[FD entry [ 


1 Division 


jLABEL RECORDS 
t 


[LABEL RECORDS [ 
1 t 


1 Procedure 


1 

[OPEN OUTPUT 


[OPEN OUTPUT [ 


1 Division 


1 or 


1 or [ 




[OPEN EXTEND 


[OPEN EXTEND [ 




1 WRITE 


[WRITE [ 




[CLOSE 


[CLOSE I 



Tne following discussion illustrates the 
steps wnich must be taken to create an 
entry-sequenced file. Assiome the VSAM 
catalog and VSAM data space have beer- 
created as previously illustrated. The 
next thing a user must do is define the 
entry in the catalog for the VSAM file. 

// JOB DEFINE FILE 

// EXEC IDCAMS,SIZE=100K 

DEFINE CLUSTER (NAME (TRANFILE) 
VOLUME (321 942) RECORDS (50 5) 
RECORDSIZE(80 80) READPW ( RO 1 4 ) 
UPDATEPW(W0104) ATTEMPTS (0) 
NONINDEXED SUBALLOCATION) 
CATALOG (VSAMCAT/SECRET) 
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The meaning of the parameters is 



NAME 
(TRANFILE) 

VOLUME 
(321942) 



RECORDS 
(50 5) 



RECORDS I ZE 
(80 80) 

READPW 
(R0104) 

UPDATEPW 
(W0104) 



ATTEMPTS (0) 



NONINDEXED 



S DEALLOCATION 



CATALOG 
(VSAMCAT/ 
SECRET) 



This is the data set name. 



This is the volume on which 
the space for the data set 
resides. 

Primary allocation is for 
50 records, secondary 
allocation is for 5 records. 

The average and maximum 
record size is 80 characters. 

The password R0104 must be 
supplied to open the file 
with the INPUT option. 

The password W0 104 must be 
supplied to open the file 
with the OUTPUT, EXTEND or 
I-O option. 

The operator is not to be 
prompted for the password 
when the file is opened. 

The file is an entry- 
sequenced file. 

Space for this file is to 
be suballocated from exist- 
ing VSAM data space on the 
volume. 

The name of the catalog into 
which this file is cataloged 
is VSAMCAT and its update 
password is SECRET. 



The COBOL program to access such a file 
would include the following statements. 

FILE-CONTROL. 

SELECT VSAMSEQ 

ASSIGN TO SYS010-AS-TESTFL 
ORGANIZATION IS SEQUENTIAL 
ACCESS IS SEQUENTIAL 
PASSWORD IS VSAMPW 
FILE STATUS IS STATKEY. 



DATA DIVISION. 
FILE SECTION. 
FD VSAMSEQ 

LABEL RECORDS ARE OMITTED. 
1 VSAMREC . 

05 FIELD1 PICTURE X(8). 

05 FIELD2 PICTURE X(72) 



WORKING-STORAGE SECTION. 

77 STATKEY PICTURE 99. 

77 VSAMPW PICTURE X(5: 



PROCEDURE DIVISION. 
BUILD- PAS SWORD. 

PERFORM PASSWORD-BUILDER. 

PERFORM PASSWORD-SCRAMBLER. 



OPEN OUTPUT VSAMSEQ . 
IF STATKEY NOT = 

GO TO ERROR- HANDLER. 
BUILD- A- RECORD. 



WRITE VSAMREC. 
IF STATKEY NOT = 

GO TO ERROR- HANDLER. 



Note: When the user gains update access 
to the file (by supplying the update level 
of the password) he has also gained read 
access. In general, when a user gains 
access to a file at a given level of 
protection, he has gained access to that 
file for all lower levels. This means that 
the above file could be opened INPUT by 
supplying the update level of the password. 
However, it could not be opened OUTPUT, 
EXTEND or 1-0 by supplying the read level 
password. 



GO TO BUILD- A- RECORD, 



In this sample program the routines 
PASSWORD-BUILDER and PAS SWORD- SCRAMBLER 
construct the update level password so 
that the file can be opened OUTPUT. These 
routines can be written in such a way 
that they are difficult to follow, thus 
improving security. 
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Note that the FILE-STATUS is checked 
after each request on the file. This 
ensures that unexpected conditions will 
be detected. 

The JCL needed to execute the program is 

// JOB 

// ASSGN SYSOIO X'130' 

// DLBL TESTFL , ' TRANFILE ' , ,VSAM 

// EXTENT SYSO 10,321942 

// EXEC program-name, SI ZE=nnnk 



Example 2 : 

This example shows the creation of a 
COBOL key-sequenced YSAK file. This 
prpgram performs the same function as 
example 1 except that now a key-seguenced 
file is being created. The records in the 
file "INREC" are in ascending key order. 

IDENTIFICATION DI7ISI0N. 



ENVIRONMENT DIVISION. 



PROCEDURE DIVISION. 
PARA1. 

OPEN INPDT INREC OUTPUT OUTREC. 

IF CEK IS NOT - ^00" GO TO CHKRTN . 
PARA2. 

READ INREC INTO OUTMASTER 
AT END GO TO PARA4. 
PARA3. 

WRITE OUTMASTER. 

IF CHK IS NOT = "00" GO TO CHKRTN. 

GO TO PARA2. 
PARA4. 

CLOSE INREC OUTREC. 

IF CEK IS NOT = "00" GO TO CHKRTN. 
FINIT. 

CLOSE INREC OUTREC. 

STOP RUN. 
CHKRTN. 

DISPLAY "ERROR. STATUS KEY VALUE 
IS" CHK 

GO TO FINIT. 

Note that in this example any Status Key 
return other than 00 causes transfer of 
control to paragraph CHKRTN. This routine 
can determine the exact cause of the error 
by checking the Status Key. Once the cause 
is determined, instructions can be issued 
according to the user's desired response to 
each type of error. 






INPUT-OUTPUT SECTION. 
FILE-CONTROL. 

SELECT INREC 

ASSIGN TO SYS005-UR-2540R-CARDIN 
SELECT OUTREC 

ASSIGN TO SYS010-OUTHAST 
ORGANIZATION IS INDEXED 
RECORD KEY IS ARG-1 
FILE STATUS IS CHK. 



DATA DIVISION. 

FILE SECTION. 

FD INREC LABEL RECORDS ARE OMITTED 

DATA RECORD IS INMASTER 
01 INMASTER PIC X (80) . 
FD OUTREC LABEL RECORDS ARE STANDARD 

DATA RECORD IS OUTMASTER. 
01 OUTMASTER. 

05 FILLER PIC X. 

05 ARG-1 PIC XXX. 

05 REM PIC X(76) . 
WORKING-STORAGE SECTION. 
77 CHK PIC XX. 



Retrieving a VSAM File 



The minimum COBOL language statements 
required to retrieve a VSAM file are 
summarized in Table 15. 

Table 15. COBOL Statements for Retrieving 
a VSAM File 



r n 


Entry-Seguenced 
File 


T ■• 1 

1 1 

|Key-Sequenced| 
1 File 1 
1 1 


{Environment 
1 Division 


SELECT 
ASSIGN 


1 SELECT 1 
1 ASSIGN 1 
(ORGANIZATION | 
1 IS INDEXED 1 
1 RECORD KEY | 
t f 


IData 

1 Division 


FD entry 
LABEL RECORDS 


|FD entry | 

1 LABEL RECORDS 1 
1 1 


1 Procedure 
1 Division 


OPEN INPUT 
READ ... 
AT END 
CLOSE 


I i 
lOPEN INPUT 1 
IREAD 1 

1 1 
1 CLOSE 1 
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The following examples show the 
retrieval of records from VSAH files. 



Example 3 ; 

This example shows the retrieval of 
records from the entry-sequenced file 
created in example 1. The records are then 
printed. 

IDENTIFICATION DIVISION. 



Example 4 : 

This example shows the retrieval of 
records from the key-seguenced file created 
in example 2. Note that in the Procedure 
Division there is a switch from sequential 
processing to random processing; this is 
permitted since ACCESS IS DYNAHIC is 
specified in the ENVIRONMENT Division. 

IDENTIFICATION DIVISION. 



ENVIRONMENT DIVISION 



ENVIRONMENT DIVISION. 



INPDT-OOTPUT SECTION. 
FILE-CONTROL 

SELECT INREC 

ASSIGN TO SYS010-AS-INMAST 

FILE STATUS IS CHK. 

SELECT PREC 

ASSIGN TO SYS005-UR-1403-S-PRNTR 



INPUT-ODTPUT SECTION. 
FILE-CONTROL. 

SELECT INREC 

ASSIGN TO SYS010-INMAST 

ORGANIZATION IS INDEXED 

ACCESS IS DYNAMIC 
RECORD KEY IS ARG-1 

FILE STATUS IS CHK. 
SELECT PREC 

ASSIGN TO SYS005-DR-1403-S-PRINTR 



DATA DIVISION. 

FILE SECTION. 

FD INREC LABEL RECORDS ARE STANDARD 

DATA RECORD IS INMASTER. 
01 INMASTER PIC X (80) . 
FD PREC LABEL RECORDS ARE OMITTED 

DATA RECORD IS POUT. 
01 POUT PIC X (80) . 
WORKING-STORAGE SECTION. 
77 CEK PIC XX. 
PROCEDURE DIVISION. 
PARA1. 

OPEN INPUT INREC OUTPUT PREC. 

IF CHK IS NOT = "00" GO TO CHKPTN. 
PARA2. 

READ INREC INTO POUT AT END GO TO 
PARA4. 

IF CHK IS NOT = "00" GO TO CHKRTN 
PARA3. 

WRITE POUT. 

GO TO PARA2. 
PASA4. 

CLOSE OUTREC PREC. 

IF CHK IS NOT = "00" GO TO CHKRTN. 
FINIT. 

STOP RUN. 
CHKRTN. 

DISPLAY »ERROR. STATUS KEY VALUE 
IS* CHK. 

GO TO FINIT. 

Note that in this example any Status Key 
return other than 00 causes transfer of 
control to paragraph CHKRTN. This routine 
can determine the exact cause of the error 
by checking the Status Key. Once the cause 
is determined, instructions can be issued 
according to the user's desired response to 
each type of error. 



DATA DIVISION. 

FILE SECTION. 

FD INREC LABEL RECORDS ARE STANDARD 

DATA RECORD IS INMASTER. 
01 INMASTER. 

05 FILLER PIC X. 

05 ^ARG-1 PIC XXX. 

05 ARG-2 PIC XX. 

05 ARG-3 PIC XX. 

05 FILLER PIC X (72) . 
FD PREC LABEL RECORDS ARE OMITTED 

•DATA RECORD IS POUT. 
01 POUT PIC X (80) . 
WORKING-STORAGE SECTION. 
77 CHK PIC XX. 
PROCEDURE DIVISION. 
PARA1. 

OPEN INPUT INREC OUTPUT PREC. 

IF CHK IS NOT = "00" GO TO CHKRTN. 
PARA2. 

MOVE "003" TO ARG-1. 

START INREC. 
PARA3. 

READ INREC NEXT RECORD AT END GO TO 
PARA 4. 

IF CHK IS NOT = "00" GO TO CHKRTN. 

IF ARG-2 IS = "02" GO TO PARA4'. 

IF ARG-3 IS NOT = "73" GO TO PARA3. 

WRITE POUT FROM INMASTER. 

GO TO PARA3.. 
PARAU. 

MOVE "101" TO ARG-1. 

READ INREC INVALID KEY GO TO CHKRTN, 

WRITE POUT FROM INMASTER. 

MOVE "103" TO ARG-1. 

READ INREC INVALID KEY GO TO CHKRTN 

WRITE POUT FROM INMASTER. 
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PARA5. Osinq ISAM Programs to Process VSAH Files 
CLOSE INREC PREC. 

IF CHK IS NOT = "00" GO TO CHKRTN . 

FINIT. Once the file is converted the 

STOP RUN. programmer can process the new VSAJi file 

CHKRTN. with his old ISAM program by converting his 

DISPLAY 'ERROR. STATUS KEY VALUE ISAM JCL to VSAM JCL . For more details on 

IS» CHK. this procedure see DOS/VS Data Management 

GO TO FINIT. Guide . 

Note that in this example any Status Key 
return other than 00 causes transfer of 
control to paragraph CHKRTN. This routine 
can determine the exact cause of the error 
by checking the Status Key. Once the cause 
is determined, instructions can be issued 
according to the user *s desired response to 
each type of error. 

lob Control Language for a YSAM File 

JCL is simplified for VSAM since all 
rSAM files must be cataloged through Access 
!ethod Services. 

The JCL to execute the program in 
sxample 1 is 

V JOB 

V ASSGN SYS010,X'233' 

V DLBL OUTHAST,'PAYFILE',#VSAH 
y EXTENT SYS010,VSAHVOL 

V EXEC EXAMPLE, SIZE=50K 

The volume on which the VSAM file was 
iefined is mounted at address 233, the 
?olume ID is VSAMVOL, and the file was 
jiven the name PAYFILE when it was defined. 
The SIZE parameter is required on the 
SXEC card for VSAM programs . 

Converting Non-VSAH Files to YSAM Files 



ISAM files can be converted to VSAM 
files so that they may be processed by a 
-OBOL program using VSAM. The conversion 
Is done through Access Method Services. 

Essentially, the conversion process 
-onsists of defining a VSAM file as the 
target for the file being converted. Then 
through the appropriate JCL and the REPRO 
::ommand, the conversion is accomplished. 

For a complete description of the 
::onversion process, see DOS/VS Utilities 
ySAM Access Method Services r and DOS/VS 
Data Management Guide . 
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DETAILED FILE PROCESSING CAPABILITIES 



The following topics are discussed 
within this chapter: 

COBOL VSAM Control Blocks 

DTF Tables 

Error Recovery for Non-VSAM Files 

Volume and File Label Handling 



the Environment Division (SELECT, RERUN, 
and SAME statements) and the Data Division 
(FD and associated records). The File 
Control Block (FCB) is generated 
dynamically at execution time by the VSAM 
library subroutines. The user may wish to 
refer to fields in these blocks for 
debugging. The format of the VSAM control 
block (Access Method Control Block — ACP) 
is not given here, as the knowledge of its 
contents is not needed by the COBOL user. 



COBOL VSAM CONTROL BLOCKS 



The compiler generates a File 
Information Block (FIB) from information in 
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CONTROL BLOCKS FOR VSAM 

The following two control blocks are required to process input/output requests for 
VSMI files. 



VSAM FILE INFORMATION BLOCK (FIB) 



The file information block, a portion of the completed object module, is used at 
execution time by the ILBDINTO, ILBDVOCO, and ILBDVIOO COBOL library subroutines for 
processing input/output verbs used with VSAM files. The FIB is built by phase 21. 

Fixed Portion: 



Disp 


lacement 




No. of 










Hex 



Decimal 



Field 
IFIBID 


Bytes 
1 


Description 

FIB identification code: X" 


I' 


1 


1 


IFIBLVL 


1 


FIB level number 






2 


2 


INAMED 


7 


External name 






9 


9 


INAMEDB 


1 


External name 






A 


10 




1 


Reserved 






B 


11 


I ORG 


1 


ORGANIZATION 














Code: 
















Bits 
0-7 


Equate 

Name 

lORGVPS 

lOfiGVIX 


Bit 

Settings 
1000 1000 

0100 1000 


Meaning 

VSAM ADDRESSED 

SEQUENTIAL 
VSAM INDEXED 


C 


12 


lACCESS 


1 


ACCESS 
Code: 


MODE 














Bits 
0-7 


Equate 

Name 

IACCSEQ 

iaccran 

lACCDYN 


Bit 

Settings 
1000 0000 
0100 0000 
0010 0000 


Meaning 
SEQUENTIAL 
RANDOM 
DYNAMIC 



13 
14 



ISWl 



Reserved 



Miscellaneous switches 



15 



Code: 



Bits 
0-7 



Equate 
Name 
ISOPTNL 
ISSAMREC 



Bit 

Settings 
1000 0000 
0010 0000 



Reserved 



Meaning 

OPTIONAL specified 
SAME RECORD AREA 
specified 



10 



16 



Reserved 



16 


22 


IRECLEN 


2 


18 


24 


IRECDBL 


2 


lA 


26 


IRECNBL 


1 


IB 


27 




1 


IC 


28 


ISTATDBL 


2 


IE 


30 


ISTATDDN 


2 


20 


32 


ISTATLDN 


2 


22 


34 




1 


23 


35 


IKEYNO 


1 



Number of bytes in longest 01-entry 

Displacement in TGT of record's first base locator cell 

Number of base locators for RECORD AREA 

Reserved 

Displacement in TGT of base locator for STATUS data-naire 

Displacement from base locator of STATUS data-name 

Length of STATUS data -name 

Reserved 

Niomber of entries in key list 
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2H 


36 


IKEYFNTL 


2 


26 


38 


IPSWISW 


1 


27 


39 


IPSHNO 


1 


28 


40 


IPSITENTL 


2 


2A 


42 




14 


38 


56 


IMISCAD 


4 


3C 


60 


ILABELAD 


4 


40 


64 


IKEYLSTA 


4 


44 


68 


IPSHLSTA 


4 


48 


72 




16 



Length of each entry in key list 

Hiscellaneous switches 

Number of entries in password list 

Length of each entry in password list 

Reserved 

Address in variable length portion of FIB for 

miscellaneous clauses 

Reserved 

Address of first key list entry 

Address of first password list entry 

Reserved 



Variable Length Portion ; 

Supplementary information for miscellaneous clauses (one for each clause) : 



Displacement 
Hex Decimal 



Field 
IMS»1 



No. of 
Bytes 
2 



Description 
Switch bytes 



Code: 

Bits 

0-7 

8-15 



Equate 

Name 

IMRREOY 



Bit 

Settings 
1000 0000 



Meaning 

RERDN at end of volume 

Reserved 



IRERUNI 



RERDN integer (field contains zeros if RERUN not 

specified) 

Slack bytes 

External-name of RERUN clause 



Key List Entry 

Displacement 
Hex Decimal Field 
KEYSW 



IRERUNN 8 

(one per user-defined key — REC0RD/ALTERNATE/RELATI7E) 



No. of 

Bytes 

1 



Description 
Miscellaneous switches 

Code: 



i 



1 


1 


IKEYLDN 


1 


2 


2 


IKEYDBL 


2 


4 


4 


IKEYDDN 


2 



Bits 
0-7 



Equate 

Name 

IKEYCOHP 



Bit 

Settings 
1000 0000 



Meaning 

Key is USAGE COMP (binary) 



Length of key data-name 

Displacement of key data-name's locator in TGT 

Data-name displacement from locator 



Password List Entry: (one per password) 
IPSWDIXN 1 



1 


1 


IPSWDLDN 


1 


2 


2 


IPSWDDBL 


2 


4 


4 


IPSWDDDN 


2 



Associated index number 

= none 

1 = primary 

Length of password data-name 

Displacement of password data-name's locator in TGT 

Data-name displacement from locator 
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VSAH FILE CONTROL BLOCK (FCB] 



The VSAH File Control Block is created by the ILBDINTO COBOL library subroutine, 
is used by the ILBDVIOO and ILBDVOCO subroutines to interface with the VSAH system 
control subroutines 



It 



Displacement 




No. of 


Hex 


Decimal 


Field 


Bytes 








FCBID 


1 


1 


1 


FCBLVL 


1 


2 


2 


FOPENOPT 


4 


6 


6 


FCLOSOPT 


4 


A 


10 




2 


C 


12 


FCOBRTN 


4 


10 


16 


FOSERR 


4 


14 


20 


FOSELIST 


4 


18 


24 




6 


IE 


30 


FRECKEY 


1 


1F 


31 


FADVANC 


1 


20 


32 


FENDINV 


4 


24 


36 




12 


30 


48 


FOPENOPS 


4 



Description 

FCB identif icajtion code: «F» 

PCB level number 

Save area for OPEN options 

Save area for CLOSE options 

Reserved 

Address of COBOL transmitter routine 

Address of USE... ERROR declarative 

Address of aSE declarative Exit List 

Reserved 

Number of RECORD KEY 

Reserved 

Return address from INVALID KEY, AT END, or end-df-page 

Reserved for compilation-dependent fields 

Options for VSAH OPEN verb 



Code: 





Equate 


Bit 




Bits 


Name 


Settings 


Heaning 


0-7 


FOPIN 


1000 0000 


INPUT 




FOPODT 


0100 0000 


OOTPDT 




FOPIO 


0010 0000 


I-O 




FOPEXT 


0001 0000 


EXTEND 


8-15 


Reserved 






16-23 


FOPUERR 


1000 0000 


USE...E] 



24-31 Reserved 



.ERROR declarative 
address in FUSERR cell 



34 



52 



FCLOSOPS 



VSAH CLOSE options 



Code: 



Bits 

0-7 

8-31 



Equate 
Name 
PCLLOCK 
Reserved 



Bit 

Settings 
0001 0000 



Heaning 
LOCK 



38 



56 



FSW1 



Hiscellaneous switches 



Code: 



Bits 
0-7 



8-31 



Equate Bit 

Name Settings Heaning 

FSOPEN 1000 0000 Pile is open 

FSLOCKED 0100 0000 File is closed with lock 

FSOPTNL 0010 0000 Optional file not present 

FSOKACT 0001 0000 Successful action has 

occurred since open 
FSEOF 0000 1000 Sequential read has 

encountered end-of-file 
FSVCORE 0000 0100 Hain storage to process 

this open has been 

acquired 

Reserved 
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3C 



60 



FTESTMT 



Transmission statement switches 
Code: 



Bits 
0-7 



8-15 



16-23 



24-31 



Equate 

Name 

FTREAD 

FTWBITE 

FTEEWRT 

FTSTART 

FTDELEt 

FTINVKEY 

FTATEND 

FTNEXT 

PTKEY 

FTSECHGT 

FTSfiCHEQ 

FTSRCHGE 

Reserved 



Bit 

Settings 
0000 0100 
0000 1000 

0000 1100 

0001 0000 
0001 0100 
1000 0000 
0100 0000 
0000 0010 
0000 0001 
1000 0000 
0100 0000 
0010 0000 



Heaninqs 

READ statement 

WRITE statement 

REWRITE statement 

START 

DELETE statement 

INVALID KEY 

AT END 

NEXT 

KEY 

GREATER THAN 

EQUAL TO 

NOT LESS THAN 



40 


64 


PSYSCBAL 


4 


44 


68 


FSYSCBLL 


4 


48 


72 


FSYSCBNO 


2 


4A 


74 


FKEYLEN 


2 


4C 


76 


FRECCNT 


4 


50 


80 


FFIBAD 


4 


54 


84 


FWORKAD 


4 


58 


88 


FRECA 


4 


5C 


92 


FSAMRECA 


4 


60 


96 


FSTATKEY 


2 


62 


98 


FLASTREQ 


1 



Address of system control blocks address list 

Address of system control blocks lenqths list 

Number of system control blocks {DTF, DCB, ACB) 

Length of KEY data-name 

Record count for checkpoint subroutine, if RERUN 

specified 

Address of File Information Block (FIB) 

Address of system-dependent work area 

Address of current record area 

Address of SAME RECORD AREA 

STATUS KEY work area 

Last I/O statement 



Code: 



63 



99 



13 





Equate 


Bit 




Bits 


Name 


Settings 


0-7 


FLASTRD 


0000 


0100 




FLASTWRT 


0000 


1000 




FLASTRWT 


0000 


1100 




FLASTSTR 


0001 


0000 




FLASTDLT 


0001 


0100 




FLASTOPN 


0001 


1000 




FLASTCLO 


0001 


1100 


Reserved 







Heaninqs 
READ statement 
WRITE statement 
REWRITE statement 
START statement 
DELETE statement 
OPEN statement 
CLOSE statement 



i 
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DTP TABLES 



Whenever COBOL imperative-statements 
(READ, WRITE, REWRITE, etc.) are used in a 
program to control the input and/or output 
of records in a file, that file must be 
defined by a DTP. A DTP is created by the 
compiler for each file opened in a COBOL 
program from information specified in the 
Environment Division, PD entry, and 
input/output statements in the source 
program. The DTP for each file is part of 
the object module that is generated by the 
compiler. It describes the characteristics 
of the logical file, indicates the type of 
processing to be used for the file, and 
specifies the storage areas and routines 
used for the file. 

The DTP'S generated for the permissible 
combinations of device type and COBOL file 
processing technigue are as follows: 

DTPCD Card reader, punch — 

organization and access 
seguential 

DTPPR Printer — organization and 
access seguential 

DTFMT Tape — organization and access 
seguential 

DTPSD nass storage device — 
organization and access 
sequential 

DTPDA Mass storage device — 

organization direct, access 
seguential or random 

DTFIS Mass storage device — 

organization indexed, access 
seguential or random 



DTPDD 3510 diskette — organization and 
access seguential 



Because of their limited interest for 
the COBOL programmer, the contents and 
location of the fields of each of the DTP 
types are not discussed in this 
publication. However, there are certain 
fields which immediately precede the 
storage area allocated for the DTP which 
are pertinent. These fields are provided 
on the listing in hexadecimal if an 
abnormal termination occurs and the SYHDMP 
option is in effect. The SYHDMP option is 
described in detail in the chapter 
"Symbolic Debugging Peatures." Pields 
preceding the DTP are described below. 



For magnetic tape files (DTFHT) or 
sequentially organized files on mass 
storage devices (DTPSD) , a 26-byte Pre-DTP 
is reserved in front of the DTP. The 
fields of the Pre-DTP are shown in Table 
T6. If any option is not specified, the 
field will contain binary zeros . 



When actual track addressing is used for 
files with direct organization and random 
access (DTPDA) , a variable-length Pre-DTP 
is reserved. The fields of the Pre-DTP are 
shown in Table 23. If any option is not 
specified, the field will contain binary 
zeros. 

When relative track addressing is used 
for files with direct organization and 
random access (DTPDA) , a variable-length 
Pre-DTP is reserved. The fields of the 
Pre-DTP are shown in Table 18. If any 
option is not specified, the field will 
contain binary zeros. 
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Table 16. Fields Preceding DTFMT and DTFSD 

r 



2 bytes I Length of nonstandard label, if present 



1 byte 



Number of reels (as specified in the ASSIGN clause) when file is opened * 



1 byte 



Number of reels remaining (i.e., file not completely read) * 



2 bytes 



Maximum record length if records are variable, blocked and APPLY WRITE-ONLY 
not specified. 



iS 



4 bytes 



REEL 
Address of label declarative with BEGINNING option 

UNIT 



4 bytes 



REEL 
Address of label declarative with ENDING option 

UNIT 



4 bytes 



Address of label declarative with ENDING FILE option 



4 bytes 



Address of label declarative with BEGINNING FILE option 



1 byte 



Switch — FF if closed WITH LOCK; otherwise, the switch is used as shown in 

Table 23 



3 bytes I Address of USE AFTER STANDARD ERROR declarative 



DTFHT/DTFSD 



f- 



11 For INPUT files with nonstandard labels only, 



Table 17. Fields Preceding DTFDA — ACCESS IS RANDOM — Actual Track Addressing 



19-263 
I bytes 
l- 



ACTUAL KEYi 



i 



I 8 bytes 

l- 



SEEK Address2 



1 2 bytes 



Error bytes 3 



I 4 bytes 



Address of file extent information 



14 bytes 



Address of label declarative with ENDING FILE option 



4 bytes 



t- 



Address of label declarative with BEGINNING FILE option 



1 1 byte 
I 



Switch — FF if closed WITH LOCK; otherwise the switch is used as shown in 
Table 23 



13 bytes! Address of USE AFTER STANDARD ERROR declarative 

I 1 : 



DTFDA 



h 



(lACTUAL KEY specified in last executed WRITE statement 

|2In the form MBBCCHHR 

pThis area is reserved by the Supervisor and assigned the name ERRBYTE. For a 

I complete discussion, refer to the publication DOS/VS Supervisor and I/O Macros , 

I Order No. GC24-5037. 
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Table 18. 
I r 



Fields Preceding DTFDA — ACCESS IS BftNDOH — Relative Track Addressinc 



5-258 I 

bytes I ACTUAL KEY* 
+ 



4 bytes I SEEK address2 



3 bytes I Last extent used^ 
1 



1 byte I Not used 



2 bytes I Error bytes* 



1 byte I Index to last extent used in the Disk Extent Table 



3 bytes I Address of Disk Extent Table in the DTF 



4 bytes I Address of label declarative with EHDING FILE option 



U bytes I Address of label declarative with BEGINNING FILE option 
f- 



1 byte I Switch — FF if closed WITH LOCK; otherwise the switch is used as shown in 
I Table 2 3 



3 bytes I Address of USE AFTER STANDARD ERROR declarative 

I 



DTFDA 



lACTDAL KEY specified in the last executed WRITE statement 
2In the form TTTR 
3ln the form TTT 

*This area is reserved by the D0S/7S Supervisor and assigned the name ERRBYTE. For a 
complete discussion, refer to the publication DOS/VS Supervisor and I/O Macros . 
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When actual track addressing is used for 
files with direct organization and 
sequential access (DTFDA) , a 31-byte 
Pre-DTF is reserved. The fields of the 
Pre-DTF are shown in Table 19. If any 
option is not specified, the field will 
contain binary zeros. 

When relative track addressing is used 
for files with direct organization and 
sequential access (DTFDfi) , a 31-byte 



Pre-DTF is reserved. The fields of the 
Pre-DTF are shown in Table 20. If any 
option is not specified, the field will 
contain binary zeros. 



For files whose organization is indexed, 
eight bytes are reserved preceding the DTF, 
as shown in Table 21. The fields preceding 
the DTFDD for the 35U0 are shown in Table 
22. 



Table 19. Fields Preceding DTFDA — ACCESS IS SEQUESTIAL — Actual Track Addressing 



1 - - 

|8 bytes 




SEEK address 1 


1 

I 


1 

j5 bytes 
1 


1 
IDL0C2 1 

1 


t 

12 bytes 
1 


Error bytes^ | 

t 


|4 bytes 
1 


Address of file extent information I 

1 


1 

14 bytes 
1 


I 
Address of label declarative with ENDING FILE option | 

1 


|4 bytes 
1 


Address of label declarative with BEGINNING FILE option 

• 


1 
1 


I 1 byte 

1 
1 


1 
Swxtch — FF if closed WITH LOCK; otherwise the switch is used as shown in | 
Table 23 I 

1 


i 

|3 bytes 
1 1 


Address of USE AFTER STANDARD ERROR declarative | 

1 



DTFDA 



i 



Pln the form MBECCHHR 

I ^Address (returned by the system) of next record in the form CCKHR 

I 3This area is reserved by the DOS/VS Supervisor and assigned the name ERRBYTE. For a 

I complete discussion, refer to the publication DOS/VS Supervisor and I/O Macros . 
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Table 20. Fields Preceding DTPDA — ACCESS IS SEQUENTIAL -- Relative Track Addressing 



r- 1 

\ii bytes 


SEEK address* 


1 


i 1 

|3 bytes 


Last extent used^ 1 


i 1 

1 1 byte 
1 1 


[■■ -■■ ■— — ■■ - - - , „ _ 1 

Not used 1 


\H bytes 
1 


IDL0C3 1 

t 


t 

1 1 byte 
1 


I 
Not used 1 

f 


( 

|2 bytes 

1 


1 
Error bytes* I 

1 


i 

1 1 byte 
1 


I 
Index to the last extent used in the Disk Extent Table I 

1 


|3 bytes 

1 


1 
Address of Disk Extent Table in the DTF I 


1 — ■ 

\H bytes 

1 


1 
Address of label declarative with ENDING FILE option f 


|4 bytes 
1 


r '"■"■"' ' 1 
Address of label declarative with BEGINNING FILE option I 

r 


1 1 byte 

1 
1 


1 
Switch — FF if closed with LOCK; otherwise the switch is used as shown in I 

Table 23 1 

1 


i 

1 3 bytes 

L. 


1 

Address of USE AFTER STANDARD ERROR declarative I 

L, . ...„ ... ., ... _.., -.., ,. - , _. ... 1 



DTFDA 



|»In the form TTTR 

I 2In the form TTT 

I ^Address (returned by the system) of the next record in the form TTTR 

I ♦This area is reserved by the DOS/TS Supervisor and assigned the name ERRBYTE. For a 

I complete discussion, refer to the publication DOS/VS Supervisor and I/O Hacros . 



Table 21. Fields Preceding DTFIS 



1 2 bytes HJnused 



H 



|2 bytes I Displacement of record key within record 
I 1- 



|1 byte {Switch — FF if closed WITH LOCK; otherwise the switch is used as shown in 
I I Table 2 3 
I 



1 

1 3 bytes I Address of USE AFTER STANDARD ERROR declarative 

I • 



\ 



DTFIS 
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Table 22. Fields Preceding DTFDU 



1 1 

1 4 bytes I Unused 



|1 byte I DTP switch — FF if closed with LOCK 
I f- 



13 bytes I Address of USE AFTER STANDARD ERROR declarative 

I 1 ^ 



DTFDU 



Some files can be opened several 
different ways in one COBOL program. 

For DTFCD and DTFPR, only one DTF will 
be generated for each file. 

For DTFHT, a maximum of three DTF»s may 
be needed — one each for OPES INPUT, OPEN 
INPUT REVERSED, and OPEN OUTPUT. 

For DTFSD, a maximum of three DTF's may 
be needed — one each for OPEN INPUT, OPEN 
OUTPUT, and OPEN I-O statements. 

For DTFIS and DTFDA, only one DTF is 
needed. 



Pre-DTF Switch 



When used, this switch provides 
communication between the executing program 
and its input/output subroutines at 
execution time. The entire byte may be set 
to X»FF» to indicate that the file was 
closed WITH LOCK and cannot be reopened. 
Otherwise the switch is used as shown in 
Table 23. 



ERROR RECOVERY FOR NON-VSAM FILES 



COBOL allows the programmer to handle 
input/output errors through 1) the INVALID 
KEY clause for certain source language 
statements, and 2) the USE AFTER STANDARD 
ERROR declarative sentence. 

Input/output errors caused by the 
program can be recovered from directly by 
the procedure specified in the INVALID KEY 
clause. That is, when the system 
determines that an invalid key condition 
exists, control is returned to the 
programmer at the imperative-statement 
specified in the INVALID KEY clause. An 
invalid key condition can occur on files 
with direct or indexed organization and on 
seguentially organized disk files. The 
errors that cause an invalid key condition 
are shown in Table 24. 



Table 23. Meanina of Pre-DTF Switch 



1 Bit I Meaning, if ON 
I 



5-6 



Turned ON the first time a BTFSD 
output file is opened. The entire 
DTF is saved for subsequent OPEN 
OUTPUT statements. 



Turned ON when DTFDA or DTFSD files 
are opened I-O. 



This bit is ON to indicate 
beginning of volume user label 
processing. The bit is set OFF 
when a file is opened to indicate 
to the user label processing 
subroutine (ILBDUSLO) that 
beginning-of-f ile user labels are 
to be processed. That subroutine 
sets the bit ON after beginning- 
of-file processing to indicate that 
all subsequent calls for this 
subroutine are for beginning-of- 
volume user label processing. 



For output files with variable- 
length blocked records, this bit 
turned OFF when a file is opened 
and ON for all WHITE'S after the 
first. 



IS 



Turned ON for spanned record 
processing on a DTFDA file. 



Not used. 



New ILBDIMLO-Indicator for Rel. 2.5 
and higher (see note below) . 



i 



Note ; This bit is set by Rel. 2.5 ILBDIMLO 
and tested by transient $$BFCMUL. If this 
bit is not on, exit is taken immediately, 
because PUB pointer in DTF- 8 is incorrect. 
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Table 24. Errors Causing an Invalid Key Condition 



1 ■■ T- 

1 Organization 1 
1 1 


ACCESS 1 


- n 

OPEN 


1-0 Verb 


Condition j 

• 


1 

1 Sequential 




[SEOUENTIAL]! 


OUTPUT 


WRITE 


End of extents reached. 






1 Direct 




[SEQUENTIAL]! 


OUTPUT 


WRITE 


Track address outside file 


extents. 




1 Direct 




RANDOM 1 
1" 

1- 


INPUT 


READ 


No record found. 








OUTPUT 


WRITE 


Track address outside file 


extents. 






1-0 


READ 
REWRITE 


Track address outside file 


extents. 


I 


1 Indexed 


1- 


[ SEQUENTIAL]! 
h 


INPUT 
1-0 


START 


No record found . | 

1 
1 I 




OUTPUT 


WRITE 


Duplicate record; sequence 


check. 






RANDOM 1 


INPUT 


READ 


No record found. 








1-0 


REWRITE 






1-0 


WRITE 


Duplicate record. 







Other input/output errors cause the job 
to be cancelled unless the programmer has 
specified a USE AFTER STANDARD ERROR 
declarative. Control is transferred to 
this declarative section if the system 
determines that a "standard" error has 
occurred during input/output processing. 
In this declarative section, the programmer 



may interrogate the COBOL error bytes if he 
has specified the GIVING option of the USE 
AFTER STANDARD ERROR declarative sentence. 
The meaning of these bytes for a specified 
combination of device type and file 
processing technique is shown in Table 25. 
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Table 25. Meaning of Error Bytes for GIVING Option of Error Declarative (Part 1 of 2) 



1 r " T "1 - 1 -T ■■■ 1 \ ■■■' - - ' — 1 

II 1 1 1 I/O 1 II 1 
1 Device | Organization j ACCESS {OPEN |Verb | Condition |Byte| Eesult j 


lOnit 1 Sequential [[SEQUENTIAL]! j [Input/output j 1 [File must be closed | 
1 record 1 | III error j I and job must be j 
1 I 1 III 11 terminated. | 


[Tape ISequential |[ SEQOEHTIAL] | INPUT |READ jWrong length j 2 |Skip block if j 
II I III record 1 | return is made to j 
II 1 III II non-declarative j 
II I III II portion . j 


II 1 II 1 Parity error | 1 [Skip block if | 
II 1 III II return is made to | 
11 1 111 I ! non-declarative \ 
II 1 III II portion . | 
II t III ' ' 1 


I 1 1 I OUTPUT! WRITE 1 All exceptional conditions are handled | 

II 1 1 1 1 by the system. I 


IDASD ISequential i[ SEQUENTIAL ] | INPUT |READ |Wrong length ! 2 |Skip block if | 

I 1 1 1 I-O 1 1 record | | return is made to | 

II 1 III II non-declarative | 
II 1 III II portion . | 


! i 1 11 1 Parity error i 1 |Skip block if ! 
II 1 III II return is made to | 
II 1 11! II non-declarative | 
i 1 1 III II portion . | 


I 1 1 ! OUTPUT 1 WRITE! Parity error I 1 |Bad block written. 1 

II 1 1 T— n II II 1 


! ! 1 1 ! I Wrong length I 2 | Bad block written. I 
II 1 III record | | I 


IDASD IDirect |[ SEQUENTIAL ]| INPUT |READ [Wrong length i 2 |Heturn to statement | 
It i III record | I after BEAD. | 


11 1 II [Data check in ! 1 [Return to statement | 
II 1 III count area I ! after READ. ! 


II 1 II [Data check for! ^ | Return to statement ! 
II 1 III 3cey and/or | | after READ. ! 
II 1 III data 1 I I 
II i III ' ' 1 


IDASD [Direct [RANDOM IINPUT |READ ISame as ACCESS SEQUENTIAL (above). | 
1 1 1 [1-0 II 1 


1 1 1 r '■ " '1 1 II 1 

I 1 1 |OUTPUT|WRITE!Wrong length | 2 [Return to next | 

II 1 ill record | | statement; bad [ 
II 1 III II block written. [ 


II 1 II [Data check in [ 1 | Return to next I 
11 i III count area [ [ statement: bad | 
11 1 III II block written. | 


II 1 II [Data check for[ 4 [Return to next [ 
II 1 III key and/or ! I statement; bad | 
II 1 III data 1 ! block written. | 


II 1 I 1 |No room found | 3 [Return to next 1 

II ! ! ! ! II statement. I 
II 1 III 11 1 


[Note: If no USE AFTER STANDARD ERROR routine is specified and one of the above con- 1 
[ditions occurs, the programmer is notified of the condition and the job is cancelled. | 



I 
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Table 25» Meaning of Error Bytes for GIVING Option of Error Declarative (Part 2 of 2) 



1 1 '-' T' ' " — ■ - 1— ■- 1 ■ T- -' T- T- ■■■- -■ 1 

II 1 1 jI/O 1 II 1 
{Device | Organization | ACCESS | OPEN |Verb | Condition I Byte | Result | 


jDASD {Direct {RANDOM | I/O { REWRITE { Wrong length { 2 (Return to next { 
{ 1 1 III record | | statement; bad | 
( 1 1 III II block written . { 


1 { { II {Data check in | 1 | Return to next { 

I { 1 III count area | | statement; bad { 

II { III II block written. | 


I { 1 II {Data check in { 4 {Return to next { 

II 1 III key and/or | { statement; bad ( 
II 1 1(1 data 1 1 block written. | 


[DASD (Indexed {[ SEQUENTIAL ]( INPUT {READ (DASD error ( 1 (Return to next ( 

1 1 1 IT— n IRPHRTTFl 1 1 •~tn+-omni+- hnfl 1 


II ( ( ( 1 Wrong length | 2 ( block read or | 
1 { { III record | { written. ( 


II 1 1 (START IDASD error | 1 (Continued pro- | 
( ( ( ( ( t II cessing of file ( 
( ( 1 ill 11 permitted. ( 


1 I 1 (OUTPUT {WRITE (DASD error 1 1 (Return to next { 


( ( ( ( ( (Wrong length { 2 | block written. ( 
( 1 ( III record | | I 


{ ( ( ( { (Prime data ( 3 (File must be ( 
( 1 ( { ( 1 area full ( ( closed. { 


{ ( 1 II (Cylinder index ( 4 (File must be ( 
( ( 1 (II full I 1 closed. I 


I ( ( ( ( [Master index ( 5 (File must be | 

II ( III full 1 1 closed. ( 


(DASD (Indexed (RANDOM (INPUT (READ (DASD error ( 1 (Return to next ( 

1 1 1 1 T — O IRPURTTPl 1 1 — tn+r^mon-h* YiPifl 1 


( { ( ( ( (Wrong length ( 2 ( block read or ( 
1 ( ( ( ( 1 record ( ( written. ( 


( 1 ( (I-O (WRITE IDASD error [ 1 (Return to next | 


( ( ( ( ( (Wrong length ( 2 ( block written. ( 
1 ( [ III record | ( { 


( ( ( 1 ( (Overflow area ( 6 (Files must be ( 
1 ( ( (II full ( { closed. 1 


(3540 {Sequential (Sequential (INPUT {READ (Data check | 1 {Return to next ( 
( ( ( ( { ( (1 statement. ( 


{ ( { (OUTPUT (WRITE (Equipment ( 2 (Bad block read or ( 

( ( { ( { ( check ( ( written up until { 

( ( [ III II bad physical { 

{ ( 1 (II II record. { 
11 I ■ 1 1 1 1 1 


[Note: If no USE AFTER STANDARD ERROR routine is specified and one of the above con- [ 


[ditions occurs, the programmer is notified of the condition and the job is cancelled. [ 



158 



If the programmer includes a USE AFTER 
STANDARD ERROR routine without specifying 
the GIVING option, he must call an 
assembler language routine within the 
declarative if he wishes to interrogate the 
error bits — set either in the DTP (DTFMT, 
DTFSD, or DTFIS) or in the fields preceding 
the DTP (DTFDA) . 



Interrogation of these error bits should 
be made to the locations shown in Tables 
26, 27, 28, 29, and 30. 



Note: The byte and bit displacement in 
Tables 26, 27, 28, 29, and 30 is relative 
to zero. 



Table 26. Location and Meaning of Error Bits for DTFMT 
I 1 1 r- 



1 OPEN 






Verb 


Condition 


1 Byte* 

1 


Bit 


1 


1 INPUT 






READ 


Wrong length record 


1 

1 3 


1 1 
1 




Parity error 


! 2 


6 i 


1 OUTPUT 






WHITE 


Wrong length record 


1 3 


1 


1 

I 

1 




Parity error 


1 2 

1 


1 
6 1 


|*Within 


the 


DTF. 










1 



Table 27. Location and Meaning of Error Bits for DTFSD 



OPEN 



Verb 



Condition 



Byte* 



I 

i INPUT, I-O 



Bit 



READ 



Wrong lenqth record 



Parity error 



i 



I OUTPUT, 1-0 



WRITE 



Parity error 



|*Within the DTF, 
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Table 28. location and Meaning of Error Bits for DTFDS 

I 1 1 » 



1 ACCESS 1 


OPEN 1 


Verb 




I Condition 


1 
1 


Byte* 




Bit 1 


([SEODENTIALjl 


INPUT 1 


READ 




1 Wrong length record 


1 
1 





1 1 




1 Data check in count area 


1 
1 


1 


1 




1 Data check in key or data 


1 
1 


1 


3 1 
1 




1 No record found 


1 


1 


2 


or 4 1 


(RANDOM 1 

1 L_ 


INPUT, I-O 1 


READ 




1 Same as sequential 










1 r^ 


OUTPUT 1 


WRITE 




I Wronc length record 


1 
1 





1 

1 t 
1 




1 No room found 


1 
1 





^ 1 




1 Data check in count area 


1 

1 
1 


1 


1 


1 1- 


1 Data check in key or data 


1 

1 
1 


1 


3 1 


1 r^ 


1-0 1 
1 


REWRIT 


E 


1 Wrong length record 


1 

1 
1 





1 1 




1 Data check in count area 


1 

1 
1 


1 


1 




1 Data check in key or data 


1 
1 


1 


3 1 

1 


1 1 


1 No record found 

1 


1 

1 


1 


2 


or 4 1 
1 


|*Within error 
1 these bytes. 


bytes preceding 


DTP. 


See 


the section "DTP Tables" for 


the location 


of 1 

1 



Table 29. Location and Meaning of Error Bits for DTFIS 

I 1 1 1 



1 ACCESS 1 OPEN 


Verb 


Condition 




Byte* 




Bit 1 


|[ SEQUENTIAL]! INPUT, 1-0 


READ 


DASD error 




30 




1 




Wrong length record 




30 




1 1 


1 1 OUTPUT 


WRITE 


DASD error 




30 




1 




Wrong length record 




30 




1 I 




Prime data area full 




30 




2 1 




Cylinder index full 




30 




3 1 




Kaster index full 




30 




4 1 


1 RANDOM 1 INPUT, 1-0 


READ 
REWRITE 


DASD error 




30 




1 




Wrong length record 




30 




1 1 


1 1 1-0 


WRITE 


DASD error 




30 




1 


1 1 


Wrong length record 




30 




1 1 


1 1 


Overflow area full 




30 


! 


6 1 


|*Within the DTF. 
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Table 30. Location and Keaninq of Error Bits for DTFDO 



1 — ■ ~\ 

1 ACCESS 
1 


OPEN 


1 Verb 
I 


Condition 


Byte* 1 


T 

Bit 1 


1 

1 Sequential 


Input 
Output 


1 BEAD 

1 

1 WBITE 

1 


Data check 


3 1 


3 1 


1 

1 
1 


Fquipment check 


2 1 
I 1 


2 1 

1 



The following should be considered when 
processing tape input files: 



1. Two types of errors are returned to 
the programmer: wrong length record 
and parity check. The COBOL error 
bytes, if requested, are set to 
reflect the error condition and 
control is transferred to the USE 
AFTER STANDARD ERROR declarative 
sentence. The error block is made 
available at data-name-2 of the GIVING 
option, if specified. 



If a parity error is detected when a 
block of records is read, the tape is 
backspaced and reread 100 times before 
control is returned to the programmer. 
If the error persists, the block is 
considered an error block and is added 
to the block count found in the DTF 
table . 



2. Normal return (to the non-declarative 
portion) from a USE AFTER STANDARD 
ERROR declarative section is through 
the invoked IOCS subroutine. Thus, 
the next sequential block is brought 
into storage permitting continued 
processing of the file. (The error 
block is bypassed.) A return through 
the use of a GO TO statement does not 
bring the next block into storage; 
therefore, it is impossible to 
continue processing the file. 

The processing of a sequential disk file 
opened as input is the same as the previous 
discussion of tape files, except that the 
disk block is reread ten times before being 
considered an error block. 

COBOL cannot handle nested errors on 
sequential files. If errors occur within 
an error declarative, results are 
unpredictable . 



i 
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VOLU?!E AND FILE LABEL HANDLING 



TAPE LABELS 



Among the several types of tape labels 
allowed under the Disk Operating System 
Virtual Storage are: volume labels, 
standard file labels, user standard labels, 
and nonstandard labels. Unlabeled files 
are also permitted. The description of 
each type of label follows. 



Volume Labels 



A volume label is used whenever standard 
file labels are used. Logical IOCS 
requires a volume label with V0L1 as its 
first four characters on every standard or 
user standard labeled file. V0L2-V0L8 are 
also allowed, but must be written by 
the programmer and are only used by OS . 



Standard File Labels 



The contents of the fields of a standard 
file label are described in "Appendix B: 
Standard Tape File Labels." The 
relationship between the TLBL statement and 
a standard file label is shown in Figures 
39 and ao. 



User Standard Labels 



A user Stan 
label having D 
(user trailer 
positions. Th 
number 1 throu 
relative posit 
a group of use 
the remaining 
to the program 
present, folio 
labels. On mu 
also appear at 
header labels 
one (UKLI) at 
volume. Figur 
user labels on 



dard label is an 
RL (user header 1 
label) in the fir 
e fourth position 
gh 8 which repres 
ion of the user 1 
r labels. The co 
76 positions are 
mer. User labels 
w HDR, EOV, or EO 
Itivolume files, 

beg inning -of- vol 
are resequenced s 
the beginning of 
e m shows the po 

a file. 



80-character 
abel) or UTL 
st three 

contains a 
ents the 
abel within 
ntents of 
entirely up 
, if 

F Standard 
they may 
ume. User 
tarting with 
a new 
sitioning of 



A standard file label i 
label created when an outp 
or closed, in part by IOCS 
control statement. The fi 
characters are HDR (header 
(end-of -volume) , or EOF (e 
fourth character is a 1, i 
first of a possible eight 
remainder of the label is 
fields describing the file 
through 8 in this field ar 
input, and are not created 
the Disk Operating System 



s an 80-character 
ut file is opened 

using the TLBL 
rst three 
) , EOV 

nd-of-file) . The 
ndicating the 
labels. The 
formatted into 
. Labels 2 
e bypassed on 

on output under 
virtual Storage. 



Nonstandard Labels 



A nonstandard label may be any length. 
The contents of a nonstandard label is 
entirely programmer-dependent. It is the 
COBOL programmer's responsibility either to 
process or bypass nonstandard labels on 
input and to create them on output. 
Nonstandard label processing is not 
permitted on ASCII files. Figure 42 shows 
the positioning of nonstandard labels on a 
file. 
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Standard Tape File Label 



(— Label Identifier 

File Label Number 



L 



Version Number 
of Generation 



©<D 



File Identifier 




Supplied 
by IOCS 



Job Control TLBL Card 




■ File Security 



® 



Block Count 



System Code 



iLm i 1 1 1 n I 'rnnrn 



B 



( Reserved 
for A. S. A.) 



OiO 
1 (InHRDl) 



DOS/TOS/3 60b b|b bb bbbb|-^ 

I I 

I I 

Supplied by IOCS I 
on output V 



Oper- 
ation 

DOOU 

4 5 i T 
1111 

2222 
3333 
4444 
5555 
6666 
7 7 7 7 



5 C 3 9 

IBM so 



File Name 
OOOOOOt 

9 10 II 12 13 14 IS 
1111111 



E 
E 





2222222 
3333333 
44444444 
555S55S 5 
6666666 6 
7 7 7 77777 
6888888 6 
s 9 <) S S 9 9 ft 



)00 

lb 1 1 

2|222 
3)33 
4 144 
5)55 
6 S66 
77 7 



8 938 



File-ID 
0000000000000 

21 22 23 24 2S W 27 » » M 31 K 31 : 
1111111111111 

2222222222222 
3333333333333 
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5555555555555 
6666668666666 
77 77 777777 7 7 7 
8838888888888 



12 ', 14 15 le 17 14 15 K 



13 E 3 3 9 9 9 3 9 9 3 9 9 9 9 S S 

71 27 2J 24 23 2S 7> 71 20 3U Jl 31' 1. 3 
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Date 



900000 

3( 17 n 39 40 41 42 
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2 222222 
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3<l 11 U 39 4r, 41 42 
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No. 
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H 4S 4( 47 41 49 
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46 41 4d 49 
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so b< 92 S3 M 
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Vol. 
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77 77 



SlS999 

U bl 92 »3 }4 



File 

a Seq. 

No. 
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till 
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0000000000000 



1111111111111 
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//iTLBll DTF 
I Name 

L Blank -» 



8-5 ponch" 



Date - yy/d or yy/dd or yy/ddd (on Input or Output) 
Retention Period - d-dddd (on Output only) 



Notes: 

1 AAaximum size TLBL fields 
are shown. 

• Any field (except Ident, 
Operation, and Date) 
may be from 1 position to 
the maximum shown. IOCS 
fills in the remaining 
positions of the label field. 

♦ Ident and Operation must 
be as shown. 

» Date may be 4- 6 positions; 
Retention period, 1 - 4. 

2 If a field is omitted, shift the 
following comma and fields 
to the left. 

IOCS supplies a default value 
for the label field on output. 

3 No comma follows the last 
field used. 
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r- File Label Number 
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File Serial 
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Sequence 
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of Generation 



W 

Creation Dote 
b y y d d d 



File Security 
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Job Control TLBL Card 
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LABEL PROCESSING CONSIDERATIONS 



Label considerations for VSAM are 
discribed in the chapter "Virtual Storage 
Access Hethod (VSAS)". 

The labels which may appear on tape are 
shown in Figures 40 and 41 . The compiler 
allows the programmer to work with files 



containing all the previously mentioned 
labels as well as with unlabeled files. 



If user standard labels are to be 
created or checked in the COBOL program, 
the USE AFTER BEGINNING/ENDING LABELS 
declarative sentence and the LABEL RECORDS 
clause with the data-name option must be 
specified. 



Load Point Barker 
I 



R N 



N R N 



N P 



P P 



R R N 



N 



P P R N 



N P 



P R 



y-" 
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+ 



End of Tape Marker 



V R E N 



N P 



P R R 



1 — I — I — I — I — I — I — I — I — r — I — r 

«-H |E|E|-|E|U|-|D| I 1 

FILE #2 jT|0|0|-|0|T|-tT|T|T| 
|M|V|Y|-|V|L|-|L|M|M| 
I |1|2|-|8|1t-|8| I I 

I I i I I I I I I L ., t 



Notes : R = Required, processed by IOCS. 

N = Permitted, but not written or checked, by IOCS and not available to 

programmer. 

P = Processed by IOCS and available to user. 
t 

Figure 41. Standard, User Standard, and Volume Labels 






Load Point Marker 
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FILE #1 
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|S| |S| 

J I I L 



Notes : R = Required, processed by IOCS 
= Optional. 
C = Written by COBOL compiler. 



Figure 42. Nonstandard Labels 
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Header labels are written or read when 
the file is opened or when a volume switch 
occurs. Trailer labels are written when 
the physical end of the reel is reached, or 
when a CLOSE REEL or CLOSE file-name is 
issued. Trailer labels are read on each 
reel except the last when a tapemark is 
reached. For the last reel (i.e., EOF 
labels) , trailer labels are not read until 
the file is closed. 



For multivolume input files with 
nonstandard labels, the programmer must 
specify the intecrer-1 option of the source 
language ASSIGN clause, where integer-1 is 
the number of reels in the file. This 
number can be overridden at execution time 
by storing a nonzero integer in the special 
register NSTD-REELS before opening the 
file. The number of reels is then 
available to the programmer while the file 
is opened both in the special register 
NSTD-REELS and in the field reserved for 
this purpose which precedes the DTF table 
for DTFMT (see "DTF Tables" in this 
chapter). In addition, the number of reels 
remaining after each volume switch can also 
be found in the field reserved for this 
purpose which precedes the DTF table for 
DTFMT. 



When processing a multivolume file with 
nonstandard labels (i.e., when the 
data-name option of the LABEL RECORDS 
clause is specified) , if the programmer 
wishes to stop reading or writing before 
the physical end of a reel is reached, he 
must set a switch in the appropriate 
declarative section. In the Procedure 
Division, he can either CLOSE REEL or CLOSE 
FILE depending on the switch setting. 
Volume switching is done by LIOCS when 
CLOSE REEL is executed. 

Note : An unlabeled multivolume tape file 
should not be CLOSE WITH LOCK between two 
reels. 
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Sample Programs 



© 



The second file on the input reel is 
not used in this program and is 
bypassed through use of the POSITION 
option of the MULTIPLE FILE TAPE 
clause. 

The first and second input files are 
closed by the execution of the CLOSE 
statement with the NO REWIND option, 
leaving the tape positioned in 
mid-reel for the next OPEN. 

All volumes with the exception of the 
last volume of the multivolume output 
file are closed by a close statement 
with the REEL option. Volume 
switching is performed as noted in 
Step® . 

The second and third input files 
processed by the program are opened by 
an OPEN statement with the NO REWIND 
option. 

At job completion, a standard CLOSE is 
issued to reposition the tapes of the 
closed files at their physical 
beginnings. 

An L3LTYP control statement is 
included because a tape file requiring 
label information is to be processed. 

Alternate assignments have been made 
for SYS011. Because these alternate 
assignments are in the sequence in 
which the ASSGN statements are 
submitted, the first volume of the 
output file will be on tape drive 282, 
the second on 283, and the third on 
181. When the first CLOSE OUT-PUT 
REEL statement is executed, a standard 
EOV label is written on the volume 
assigned to drive 282 and the reel is 
rewound and positioned at its physical 
beginning. The next WRITE RECO 
statement executed will then be 
written on the volume mounted on drive 
283. 

Although the file OUT-PUT consists of 
multiple volumes, only one TLBL 
control statement need be submitted. 
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Qj All input files residing on the same 
volume are assigned to the same 
symbolic unit. 



Figure 44 is a sample program that 
illustrates the manner in which the 
multivolume file created in Figure 43 is 
read as an input file. The sample program 
also creates a multifile volume with 
standard labels. 

(ij All output files residing on the same 
volume are assigned to the same 
symbolic unit. 

The name field of the system-name in 
the ASSIGN clause is specified. This 
is the external -name by which the file 
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is known to the system. When 
specified, it is the name that appears 
in the filename field of the DLBL or 
TLBL job control statements. 



The name field of the system-name of 
the ASSIGN clause is specified. These 
names will appear on the TLBL control 
statements that refer to these files. 



® 



(2) For the multivolume input file IN-PUT, 
the AT END option of the READ 
statement applies only to the last 
volume containing the EOF label. For 
prior volumes containing EOV labels, 
automatic volume switching will take 
place as indicated in the ASSGN 
control statements pertaining to the 
file IN-POT. 

The first and second file written on 
the volume are closed using the NO 
REWIND option of the CLOSE statement. 
This option leaves the tape positioned 
in mid-reel following the EOF label of 
the file just closed. 

At job's completion, a standard CLOSE 
is issued to reposition the tapes of 
the closed files at their physical 
beginning, 

A LBLTYP control statement is included 
because tape files requiring label 
information are being processed. 

There are three TLBL control 
statements for the volume assigned to 
SYS013, one for each file referenced 
on the volume. The filename field of 
the TLBL control statements for these 
files contains the names used in the 
ASSIGN clauses of the COBOL source 
program, not the programmer logical 
unit name. 

(Y) Alternate assignments have been made 
for SYS012 to handle the multiple 
volumes of the file IN-PUT. 

Figure 45 illustrates the creation of an 
unlabeled multivolume file. The number of 
output volumes is determined dynamically 
during program execution. The program's 
input consists of the labeled multifile 
volume created in Figure 44. 

(V) All input files residing on the same 
volume are assigned to the same 
symbolic unit. 
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The MULTIPLE FILE TAPE clause is not 
required for the multifile volume 
because each file is being processed 
in the sequence in which it appears on 
the reel. A rewind will not be 
executed for any file on the reel 
except for that processed last. 

The CLOSE statement for files IN-PUT-1 
and IN-PUT-2, and the OPEN statement 
for files IN-PUT-2 and IN-PUT-3, use 
the NO REWIND option. This leaves the 
tape positioned in mid-reel for the 
multifile volume's next OPEN 
statement. 

When it has been determined from the 
input data that a new output reel is 
required for the multivolume output 
file, a CLOSE OUT-PUT REEL statement 
is executed, processing is halted, and 
a message is issued to the operator 
which requests a new volume to be 
mounted. 

At job's completion, a standard CLOSE 
is issued to reposition the tapes of 
the closed file at their physical 
beginning. 

An LBLTYP control statement is 
included because tape files requiring 
label information are being processed. 

There are three TLBL control 
statements for the volume assigned to 
SYS014, one for each file referenced 
on the volume. The filename field of 
the TLBL control statements for these 
files contains the names used in the 
ASSIGN clauses of the source program 
and not the programmer logical unit 
names. 

Only one tape drive is assigned to the 
multivolume file OUT-PUT. Therefore, 
each time a volume is closed, 
processing must be halted and the 
operator informed to mount anew tape. 
This is illustrated in Step(3) . 



■ 
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// JOB SAMPLE 

* DNLABELED MULTIFILE VOLDHE TO KULTIVOLUME FILE WITH STANDARD LABELS 

// OPTION LOG, DUMP, LINK, LIST, LISTX,XREP,SYM, ERRS, NODECK 

// EXEC FCOBOL 



000010 IDENTIFICATION DIVISION. 

000020 PROGRAH-ID. SAMPLE-1. 

000030 ENVIRONMENT DIVISION. 

000040 CONFIGURATION SECTION. 

000050 SOURCE-COMPUTER. IBM-370. 

000060 OBJECT-COMPUTER. IBM-370. 

000070 INPUT-OUTPUT SECTION. 

000080 FILE-CONTROL. 

000090 SELECT INPUTl ASSIGN TO SYSO 10-UT-341 0-S-FILEl . ) ^-v 

000100 SELECT INPUT2 ASSIGN TO SYS010-UT- 341 0-S-FILE2 . > (Jj 

000110 SELECT INPUTS ASSIGN TO SYS010-UT- 341 0-S-FILE3. ) 

000120 SELECT OUT-PUT ASSIGN TO SYS01 1-UT- 341 0-S . 

000130 I-0-CONTROL. 

000140 MULTIPLE FILE TAPE CONTAINS INPUTl POSITION 1 ) ^^ 

000150 INPUT2 POSITION 3 > (Y) 

000160 INPUT3 POSITION 4.) 

000170 DATA DIVISION. 

000180 FILE SECTION. 

000190 FD INPUTl 

000200 RECORD CONTAINS 80 CHARACTERS 

000210 LABEL RECORD IS OMITTED. 

000220 01 REC1 PIC X (80) . 

000230 FD INPUT2 

000240 RECORD CONTAINS 80 CHARACTERS 

000250 LABEL RECORD IS OMITTED. 

000260 01 REC2 PIC X (80) . 

000270 FD INPUT3 

000280 RECORD CONTAINS 80 CHARACTERS 

000290 LABEL RECORD IS OMITTED. 

000300 01 REC3 PIC X (80) . 

000310 FD OUT-PUT 

000320 RECORD CONTAINS 80 CHARACTERS 

000330 BLOCK CONTAINS 3 RECORDS 

000340 LABEL RECORD IS STANDARD. 

000350 01 RECO PIC X (80) . 

000360 PROCEDURE DIVISION. 

000370 OPEN INPUT INPUTl OUTPUT OUT-PUT. 

000380 READI. 

000390 READ INPUTl INTO RECO AT END GO TO CLOSEI. 

000400 A. WRITE RECO. 

000410 B. GO TO READI. 

000420 CLOSEI. ^-^ 

000430 CLOSE INPUTl WITH Na^EWIND.(3) 

000440 C. CLOSE OUT-PUT REEL. (4) 

000450 D. OPEN INPUT INPUT2 WITH NO REWIND. (5) 

000460 READ2. ^^-^ 

000470 READ INPUT2 INTO RECO AT END GO TO CL0SE2. 

000480 PERFORM A. 

000490 GO TO READ2. 

000500 CL0SE2. ^^ 

000510 CLOSE INPUT2 WITH NO REWIND. (Zj 

000520 PERFORM C. ^"^ ^ 

000530 OPEN INPUT INPUT3 WITH NO REWIND, (s) 

Figure 43 » Processing an Unlabeled Multifile Volume (Part 1 of 2) 
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000540 READ3. 

000550 READ ISPUT3 INTO RECO AT END GO TO CLOSES, 

000560 PERFORM A. 

000570 GO TO READ3. 

000580 CLOSES. ^^ 

000590 CLOSE INPUTS OUT-PDT. f%J 

000600 STOP RUN. ^"^ 



// LBLTYP TAPE (jj 
// EXEC LNKEDT 



// ASSGN SYS010,X*281 • 

// ASSGN SYS011,X'282' 

// ASSGN SYS011,X»283»,ALT^ 

// ASSGN SYS011,XM81»,ALTj ^_^ 

// TLEL SYS011,»SULTI-VOL FILE ',99/2 14 (jj) 

// EXEC ^-^ 

Figure 43. Processing an Unlabeled Multifile Volume (Part 2 of 2) 



m 
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// JOB SAMPLE 

* LABELED HULTI70LUME FILE TO LABELED MULTIFILE VOLUME 
// OPTION LOG, DUMP, LINK, LIST, LISTX,XREF,SY?!, ERRS, NODECK 
// EXEC FCOBOL 



000010 
000020 
000030 

ooooao 

000050 
000060 
000070 
000080 
000090 
000100 
000110 
000120 
000130 
000140 
000150 
000160 
000170 
000180 
000190 
000200 
000210 
000220 
000230 
000240 
000250 
000260 
000270 
000260 
000290 
000300 
000310 
000320 
000330 
000340 
000350 
000360 
000370 
000380 
000390 
000400 
000410 
000420 
000430 
000440 
000450 



IDENTIFICATION DIVISION. 
PROGRAK-ID. SAMPLE-2. 
ENVIRONMENT DIVISION. 
CONFIGURATION SECTION. 
SOURCE-COMPUTER. IBM-370. 
OBJECT-COMPUTER. IBM-370. 
INPUT-OUTPUT SECTION. 
FILE-CONTROL. 

SELECT IN-PUT ASSIGN TO SYSO 12-UT- 34 1 0-S . 

SELECT OUT-PUTI ASSIGN TO SYS013-UT-341 0-S-FILEl .] -. 

SELECT 0UT-PUT2 ASSIGN TO SYSO 13-UT-341 0-S-FILE2 .V M J 

SELECT 0UT-PUT3 ASSIGN TO SYS013-UT-341 0-S-FILE3 . ^^ 
DATA DIVISION. 
FILE SECTION. 
FD IN-PUT 

RECORD CONTAINS 80 CHARACTERS 

BLOCK CONTAINS 3 RECORDS 

LABEL RECORD IS STANDARD. 
01 IN-REC. 

05 FILLER PIC X (4) . 

05 CODA PIC X. 

05 FILLER PIC X (6) . 

05 CODE PIC X. 

88 SW-FIL1 VALUE "9". 
88 SW-FIL2 VALUE "8". 

05 FILLER PIC X(68) . 

OUT-PUTI 

RECORD CONTAINS 80 CHARACTERS 

BLOCK CONTAINS 3 RECORDS 

LABEL RECORD IS STANDARD. 

0UT-REC1 PIC X(80) . 

0UT-PDT2 

RECORD CONTAINS 80 CHARACTERS 

BLOCK CONTAINS 3 RECORDS 

LABEL RECORD IS STANDARD. 

0UT-REC2 PIC X(80) . 

0UT-PUT3 

RECORD CONTAINS 80 CHARACTERS 

BLOCK CONTAINS 3 RECORDS 

LABEL RECORD IS STANDARD. 

0UT-REC3 PIC X (80) . 
WORKING-STORAGE SECTION. 
77 TAPE-NUMBER PIC 9 VALUE 0. 
PROCEDURE DIVISION. 

OPEN INPUT IN-PUT OUTPUT OUT-PUTI. 



FD 



01 

FD 



01 

FD 



01 



Figure 44. Reading a Multivolume File with Standard Labels; Creating a Multifile Volume 
with Standard Labels (Part 1 of 2) 
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000460 
000470 
000480 
000490 
000500 
000510 
000520 
000530 
000540 
000550 
000560 
000570 
000580 

n r* r\ e r\ ^ 

uuu j:»u 

000600 

000610 
000620 
000630 
000640 
000650 
000660 
000670 
000680 
000690 



® 



EEAD-IN. 

READ IN-PDT AT END GO TO END-OF-JOB, 

A. MOVE IN-BEC TO OUT-RECI. 
WRITE OUT-RECI. 

IF SW-FIL1 NEXT SENTENCE ELSE GOTO READ-IN 
CLOSE 0DT-PUT1 KITH NO REWIND. (3) 
OPEN OUTPUT OOT-P0T2. ^^ 

ADD 1 TO TAPE-NUMBER. 

B. PERFORM READ-IN. 

HOVE IN-REC TO 00T-REC2. 

WRITE 0UT-REC2. 

IF SW-FIL2 NEXT SENTENCE ELSE GQ_TO B. 

CLOSE 0UT-PUT2 WITH NO REWIND. 

OPEN OUTPUT 0UT-PUT3. 

ADD 1 TO TAPE-NUMBER. 

C. PERFORM READ-IN. 
HOVE IN-REC TO 0UT-REC3, 
WRITE 0UT-REC3. 
GO TO C. 

END-OF-JOB. 

CLOSE IN-PDT. 
IF TAPE-NUMBER = 
IF TAPE-NUMBER = 

D. STOP RUN. 






CLOSE OUT-PUT 1 GO TO D. 

CLOSE 0UT-PUT2 ELSE CLOSE 0UT-PUT3 



}® 



// LBLTYP TAPE (V) 
// EXEC LNKEDT 



// ASSGN SYS018,X»283» 

// TLBL FILE1,'MULTI-FILE1 VOL* 

// TLBL FILE2,»MULTI-FILE2 VOL* 

// TLBL FILE3,»MULTI-FILE3 VOL* 

// ASSGN SYS012,X»281» 

// ASSGN SYS012,X»282*,ALT) /T\ 

// ASSGN SYS012,X*181*,ALTj W 

// TLBL SYSQ12, »MULTI-VOL FILE* 

// EXEC 



® 






Figure 44. Reading a Multivolume File with Standard Labels; Creating a Multifile Volume 
with Standard Labels (Part 2 of 2) 
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// JOB SAMPLE 

* LABELED HULTIFILE VOLOME TO UNLABELED MDLTIVOLDHE FILE 

// OPTION LOG, DUMP, LINK, LIST, LISTX,XREF,SYM,EBRS,NODECK 

// EXEC FCOBOL 



000010 IDENTIFICATION DIVISION. 

000020 PROGRAM-ID. SAMPLE-3. 

000030 ENVIRONMENT DIVISION. 

000040 CONFIGURATION SECTION. 

000050 SOURCE-COMPUTER. IBa-370. 

000060 OBJECT-COMPUTER. IBM-370. 

000070 INPUT-OUTPUT SECTION. 

000080 FILE-CONTROL. 

000090 SELECT IN-PUT-1 ASSIGN TO SYS014-UT-341 0-S-FILEl .) 

000100 SELECT IN-PUT-2 ASSIGN TO SYSO 14-UT- 341 0-S-FILE2. > Mj 

000110 SELECT IN-PUT-3 ASSIGN TO SYSO 14-UT-341 0-S-FILE3 .) ^^ 

000120 SELECT OUT-PUT ASSIGN TO SYSO 15-UT- 341 0-S . 

000130 DATA DIVISION. 

000140 FILE SECTION. 

000150 FD IN-PUT-1 

000160 RECORD CONTAINS 80 CHARACTERS 

000170 BLOCK CONTAINS 3 RECORDS 

000180 LABEL RECORD IS STANDARD. 

000190 01 IN-REC1 PIC X(80). 

000200 FD IN-PDT-2 

000210 RECORD CONTAINS 80 CHARACTERS 

000220 BLOCK CONTAINS 3 RECORDS 

000230 LABEL RECORD IS STANDARD. 

000240 01 IN-REC2 PIC X (80) . 

000250 FD IN-PUT-3 

000260 RECORD CONTAINS 80 CHARACTERS 

000270 BLOCK CONTAINS 3 RECORDS 

000280 LABEL RECORD IS STANDARD. 

000290 01 IN-REC3 PIC X{80). 

000300 FD OUT-PUT 

000310 RECORD CONTAINS 80 CHARACTERS 

000320 BLOCK CONTAINS 3 RECORDS 

000330 LABEL RECORD IS OMITTED. 

000340 01 OUT-REC. 

000350 05 FILLER PIC X (4) . 

000360 05 CODA PIC X. 

000370 88 HI VALUE "9". 

000380 05 FILLER PIC X (6) . 

000390 05 CODE PIC X. 

000400 88 LO VALUE "S". 

000410 05 FILLER PIC X(68). 

000420 PROCEDURE DIVISION. 

000430 OPEN INPUT IN-PUT-I OUTPUT OUT-PUT. 

000440 IN-1. 

000450 READ IN-PUT-1 INTO OUT-REC AT END GO TO CLOSEI. 

000460 TESTER. -^ 

000470 IF HI AND LO PERFORM CLOSE-OUT ELSE WRITE OUT-REC. (Y) 



J© 



000480 A. GO TO IN-1. 

000490 CLOSEI. 

000500 CLOSE IN-PUT-1 WITH NO REWIND. 

000510 OPEN INPUT IN-PUT-2 WITH NO REWIND 

000520 IN-2. 

000530 READ IN-PUT-2 INTO OUT-REC AT END GO TO CL0SE2. 

000540 PERFORM TESTER. 

000550 GO TO IN-2. 



Figure 45. Creating an Unlabeled Multivolume File (Part 1 of 2) 
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000560 CL0SE2. 

000570 CLOSE IN-PUT-2 WITH NO REWIND. I Cl) 

000580 OPEN INPUT IN-PUT-3 WITE NO REWIND./ w' 

000590 IN-3. 

000600 READ IN-PUT-3 INTO OOT-REC AT END GO TO CL0SE3. 

000610 PERFORM TESTER. 

000620 GO TO IN-3. 

000630 CLOSE-OUT. 

0006<*0 CLOSE OUT-PUT REEL. 

000650 STOP "REMOVE TAPE ON SYS015 AND MOUNT NEW TAPE 

000660 CL0SE3. ^^ 

000670 CLOSE IN-PUT-3 OUT-PUT. (AJ 

000680 STOP RUN. 



// LBLTYP TAPE (T) 
// EXEC LNKEDT 



// ASSGN SYS014,X»283* 

// TLEL FILE1,'»ULTI-FILE1 VOL » j ^^ 

// TLSL FILE2, »MDLTI-FILE2 VOL* > (fi) 

// TLBL FILE3, »MULTI-FILE3 VOL » ) 

// ASSGN SYS015,X'282» (t) 

// EXEC ^^ 

Figure 45. Creating an Unlabeled Multivolume File (Part 2 of 2) 
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MASS STORAGE FILE LABELS 



User Labels 



The IBM Disk Operating System/Virtual 
Storage provides postive identification and 
protection of all files on mass storage 
devices by recording labels on each volume. 
These labels ensure that the correct volume 
is used for input, and that no current 
information is destroyed on output. 

The mass storage labels always include 
one volume label for each volume and one or 
more file labels for each logical file on 
the volume. There may also be u ser header 
labels and user trailer labels. 



Volume Labels 



The programmer can include additional 
labels to further define his file. The 
labels are referred to as user standard 
labels. They cannot be specified for 
indexed files. A user label is an 
80-character label containing DHL (user 
header label) or DTL (user trailer label) 
in the first three character positions. 
The fourth position contains a number 1 
through 8 which represents the relative 
position of the user label with a group of 
user labels. The contents of the remaining 
76 positions is entirely up to the 
programmer. User header and trailer labels 
are written on the first track of the first 
extent of each volume allocated by the 
programmer for the file. User header 
labels are reseguenced starting with one 
(URU) at the beginning of each new volume. 



The volume label is an 80-byte data 
field preceded by a 4-byte key field. Both 
the key field and the first four bytes of 
the data field contain the label identifier 
YOLl. IOCS creates a standard volume label 
for every volume processed by the Disk 
Operating System/Virtual Storage. It is 
always the third record on cylinder 0, 
track 0. The format and contents of a 
standard volume label can be found in the 
publication DOS/VS Disk Labels . 



Standard File Labels 



LABEL PROCESSING CONSIDERATIONS 



Files on Mass Storage Device Opened as 
Input 



1. Standard labels checked 

a. The volume serial numbers in the 
volume labels are compared to the 
file serial numbers in the EXTENT 
card. 



A standard file la 
particular logical fi 
location (s) on the ma 
contains information 
destruction of curren 
file label for a file 
storage device is a 1 
created {OPEN/CLOSE 
using the DLBL contro 
fields contained with 
three standard format 



bel identifies a 

le, gives its 

ss storage device, and 

to prevent premature 

t files. A standard 

located on a mass 
40-character label 
UTPUT) in part by IOCS 
1 statement. The 
in the label follow 
s. 



b. Fields 1 through 3 in Format 1 
label are compared to the 
corresponding fields in the DLBL 
card. 

c. Each of the extent definitions in 
the Format 1 and Format 3 labels 
is checked against the limit 
fields supplied in the EXTENT 
card . 

User labels checked 



3. 



Format 1 is used for all logical 
files. The contents of the fields of 
a Format 1 label is discussed in 
"Appendix C: Standard Mass Storage 
Device Labels." 

Format 2 is reguired for indexed 
files. The contents of the fields of 
a Format 2 label can be found in the 
publication DOS/VS Disk Labels . 

Format 3 is reguired if a logical file 
uses more than three extents of any 
volume. The contents of the fields of 
a Format 3 label can be found in the 
publication DOS/VS Disk Labels . 



If user header labels are 
indicated for directly or 
sequentially organized files, they 
are read as each volume of the 
file is opened. After reading 
each label, the OPEN routine 
branches to the programmer's label 
routine if the appropriate USE 
AFTER STANDARD LABEL PROCEDURE 
declarative is specified in the 
source program. The LABEL RECORDS 
clause with the data-name option 
must be specified in the Data 
Division. The programmer's label 
routine then performs any 
processing reguired. 
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If user trailer labels are 
indicated on a sequential file, 
they are read after reaching the 
end of the last extent on each 
volume when the file is closed, 
provided end-of-file has been 
reached. Trailer labels are 
processed by the programmer's 
label routine if the appropriate 
USE AFTER STANDARD LABEL PROCEDURE 
declarative is specified in the 
source program. The LABEL RECORDS 
clause with the data-name option 
must be specified in the Data 
Division. 



User header labels created 

a. If user header labels are 

indicated by the presence of the 
appropriate USE AFTER STANDARD 
LABEL PROCEDURE declarative and 
the LABEL RECORDS clause with the 
data-name option, the programmer's 
label routine is entered to 
furnish the labels as each volume 
of the file is opened. This can 
be done for as many as eight user 
header labels per volume. As each 
label is presented, IOCS writes it 
out on the first track of the 
first extent of the volume. 



Files on Mass Storage Devices Opened as 
Output 



1. Standard labels created 



a. The volume serial numbers in the 
volume labels are compared to the 
file serial numbers in the EXTENT 
card. 



b. The extent definitions in all 

current labels on the volume are 
checked to determine whether any 
extend into those defined in the 
EXTENT card. If any overlap, the 
expiration date is checked against 
the current date in the 
Communication Region of the 
Supervisor. If the expiration 
date has passed, the old labels 
are deleted. If not, the operator 
is notified of the condition. 



If user trailer labels are 
indicated by the presence of the 
appropriate USE AFTER STANDARD 
LABEL PROCEDURE declarative and 
the LABEL RECORDS clause with the 
data-name option, the programmer's 
label routine is entered to 
furnish the labels when the end of 
the last extent on each volume is 
reached. This can be done for as 
many as eight user trailer labels. 
The CLOSE statement must be issued 
to create trailer labels for the 
last volume of a sequential file 
or for a direct file. 



UNLABELED FILES 



When a multivolume tape file is opened 
as INPUT and integer as specified in the 
ASSIGN clause is greater than 1, the 
compiler will generate the following 
message to the operator: 






The new Format 1 label is written 
with information supplied in the 
DLEL card. If an indexed file is 
being processed, the DTFIS routine 
supplies information for the 
Format 2 label. 



The information in the EXTENT card 
is placed in the Format 1 labels 
and, if necessary, in the 
additional Format 3 labels. 



C126D IS IT EOF? 



The operator must respond either with N if 
it is not the last reel, or with Y if it is 
the last reel. If it is end-of-file, 
control passes to the imperative-statement 
specified in the AT END phrase of the READ 
statement; if it is not end-of-file, 
processing of the next volume is initiated. 

If the integer specified in the ASSIGN 
clause is not greater than 1, control 
always passes at end-of -volume to the 
imperative-statement specified in the AT 
END phrase of the READ statement. 
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PROCESSING fiSCII TAPE FILES 



The IBM DOS/VS COBOL Compiler and 
Library support the American National 
Standard Code for Information- Interchange 
(ASCII) as well as EBCDIC. This support 
allows the user at object time to accept 
and create magnetic tapes in accordance 
with all of the followina standards: 



• American National Standard Code for 
Information Interchanqe, X3. 4-1968= 



• American National Standard Magnetic 
Tape Labels for Information 
Interchange, X3. 27-1969. 



American National Standard Recorded 
Magnetic Tape for Information 
Interchange (800 CPI, NRZI) , 
X3. 22-1967. 



FILE HANDLING 



In processing ASCII files, the supported 
record formats are fixed, undefined, and 
variable. A variable-length record on an 
ASCII file is known as a D-format record. 
ASCII support does not extend to spanned 
records. Record formats are discussed in 
detail in the chapter "Record Formats." 



For an ASCII file that contains a buffer 
offset field, the following considerations 
apply: 



If the BLOCK CONTAINS clause with the 
RECORDS option is specified, or if the 
BLOCK CONTAINS clause is omitted, the 
compiler compensates for the buffer 
offset field. 



COBOL LANGUAGE CONSIDERATIONS 



If the BLOCK CONTAINS clause with the 
CHARACTERS option is specified, the 
programmer must include the buffer 
offset as part of the physical record, 



The ASCII feature is supported by the 
following addition to IBM's implementation 
of American National Standard COBOL: 



Labels on ASCII files are processed as 
are the existing DOS/VS standard and user 
standard labels. 



The system-name specified in the ASSIGN 
clause is now coded as 

SYSnnn-UT-device-C[ -buffer offset ][ -name ] 

where 

Organization code C indicates that an 
ASCII-encoded tape file is to be 
processed . 

Buffer offset is a two-character field 
that serves to indicate the size of the 
block prefix. A block prefix, if 
present, precedes each physical record 
and is not accessible to the COBOL 
programmer. This entry may only be 
present for ASCII tape files and is only 
reguired if a non-zero block prefix 
exists. For output files, buffer offset 
may be specified as 00 for F, U, or 
D-mode records, or as 04 for D-mode 
records only- A buffer offset of 04 on 
output means that the block prefix will 
contain the length of each physical 
record. For input files, buffer offset 
may be in the range 00 through 99. 



Nonstandard label procedu 
not supported. Therefore 
STANDARD LABEL PROCEDURES 
for ASCII files. ASCII f 
tapes are supported. The 
may contain data in any o 
record formats. A comple 
tape file labels can be f 
chapter "Advanced Process 



res, however, are 
, USE BEFORE 
are not permitted 
iles on unlabeled 
se unlabeled tapes 
f the supported 
te discussion of 
ound in the 
ing Capabilities." 



i 



The ASCII option (organization code C in 
the ASSIGN clause) must not be specified 
for a file on which checkpoints are to be 
written. 



Diagnostic messages associated with 
ASCII file handling are provided. At 
compile time, E-level messages are issued 
for files whose record descriptions contain 
data formats that are inconsistent with 
ASCII conversion. At object time, a 
message is issued if an invalid sign 
configuration is present during 
translation, and the job will be 
terminated . 
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OPERATIONAL CONSIDERATIONS 



It should be noted that ASCII support 
causes translation from ASCII to EBCDIC on 
input and from EBCDIC to ASCII on output. 
Translation occurs automatically and is 
transparent to the COBOL programmer. Since 
an ASCII file is assumed to contain only 
ASCII characters, standard character 
substitution occurs when untranslatable 
configurations are present. The character 
X'1A» is substituted for invalid EBCDIC 
configurations during translation. An 
invalid ASCII configuration (high-order bit 
on) translates to the character X'3F'. 



OBTAININ G AN A SCII COLLATING SEQUENCE ON A 
SORT 



form of a leading overpunch or separate 
character, a Program Product IBM DOS/VS 
Sort/Merge program must be used. If sort 
files reside on a 3330 or 3340 device, the 
Sort program that supports these devices is 
reguired. The Program Product IBM DOS/VS 
Tape and Disk Sort/Merge, Program Number 
5746-SM1 is designed specifically for use 
with a DOS/VS system. 

To obtain an ASCII collated sort, the 
system-name in the ASSIGN clause for the 
sort work files should contain a C in the 
organization field. The class field may be 
specified as either DT or DA. (Since ASCII 
support causes translation from ASCII to 
EBCDIC on input, sort work files are not 
restricted to tapes.) 

Note that for an ASCII collated sort, 
the buffer offset field is not permitted. 



If an ASCII collated sort is desired or 
numeric sort keys contain a sign in the 



The ASCII collating sequence is listed 
in the publication IBH DOS Ful l American 
National Standard COBOL . 
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RECORD FORMATS FOR NON-VSAR FILES 



Logical records for files which are not 
VSAR files may be in one of four formats: 
fixed-length (format F) , variable-length 
(format V) , undefined (format U) , or 
spanned (format S) . All of these formats 
are not supported for all access methods. 
F-mode files must contain records of equal 
lencfthSs Files containing records of 
unequal lengths must be V-mode, S-mode, or 
U-mode. Files containing logical records 
that are longer than physical records must 
be S-mode. 



DEPENDING OS option, or if multiple record 
descriptions are all the same length. 



The number of logical records within a 
block (blocking factor) is normally 
constant for every block in the file. When 
fixed-length records are blocked, the 
programmer specifies the BLOCK CONTAINS 
clause in the file description entry in the 
Data Division. 



The record format is specified in the 
RECORDING MODE clause in the Data Division. 
If this clause is omitted, the compiler 
determines the record format from the 
record descriptions associated with the 
file. If the file is to be blocked, the 
BLOCK CONTAINS clause must be specified in 
the Data Division. 

The prime consideration in the selection 
of a record format is the nature of the 
file itself. The programmer knows the type 
of input his program will receive and the 
type of output it will produce. The 
selection of a record format is based on 
this knowledge as well as an understanding 
of the type of input/output devices on 
which the file is written and of the access 
method used to read or write the file. 

Coding considerations for non-fixed 
length records are discussed in the chapter 
"Table Handling Considerations." 



In unblocked format F, the logical 
record constitutes the block. The BLOCK 
CONTAINS clause is unnecessary for 
unblocked records. 



Format F records are shown in Figure 46. 
The optional control character, represented 
by C, is used for stacker selection and 
carriage control. When carriage control or 
stacker selection is desired, the WRITE 
statement with the ADVANCING or POSITIONING 
option is used to write records on the 
output file. In this case one character 
position must be included as the first 
character of the record. This position 
will be automatically filled in with the 
carriage control or stacker select 
character. The carriage control character 
never appears when the file is written on 
the printer or punched on the card punch. 



FIXED-LENGTE fFORKAT F) RECOR DS 



Format F records are fixed-length 
records. The programmer specifies format F 
records by including RECORDING MODE IS F in 
the file description entry in the Data 
Division. If the clause is omitted and 
both of the following are true: 

• All records in the file are the same 
size 

• BLOCK CONTAINS [integer-1 TO] 
integer-2... does not specify 
integer-2 less than the length of the 
maximum level-01 record 

the compiler determines the recording mode 
to be F. All records in the file are the 
same size if there is only one record 
description associated with the file and it 
contains no OCCURS clause with the 



Logical Record 



I C I 



Data 



Blocked Records 

I 1 1 

I Logical | Logical | Logical 
i Record | Record | Record 
I I I 



-Fixed Lenqth- 



Unblocked Record 



Logical Record 



-Fixed Length- 



i 



Figure U6. Fixed -Length (Format F) Records 
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DNDEFINED (FORMAT U) RECORDS 



Format U is provided to permit the 
processing of any blocks that do not 
conform to F or V formats. Format U 
records are shown in Figure 47. The 
optional control character C, as discussed 
under "Fixed-Length (Format F) Records," 
may be used in each logical record. 

The programmer specifies format U 
records by including RECORDING MODE IS U in 
the file description entry in the Data 
Division. D-mode records may be specified 
only for directly organized or standard 
sequential files. 

If the RECORDING MODE clause is omitted, 
and BLOCK CONTAINS [integer-1 TO] 
integer-2... does not specify integer-2 
less than the maximum level-01 record, the 
compiler determines the recording mode to 
be U if the file is directly organized and 
one of the following conditions exist: 

• The FD entry contains two or more 
level-01 descriptions of different 
lengths. 

• A record description contains an OCCURS 
clause with the DEPENDING ON option. 

• A RECORD CONTAINS clause specifies a 
range of record lengths. 

Each block on the external storage media 
is treated as a logical record. There are 
no record-length or block-length fields. 

No te : When a READ INTO statement is used 
for a U-mode file, the size of the longest 
record for that file is used in the MOVE 
statement. All other rules of the MOVE 
statement apply. 
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Figure 47. Undefined (Format U) Records 



ASCII tape file. D-format records are 
processed in the same manner as V-format 
records on tape files. 



The programmer specifies format V 
records by including RECORDING MODE IS V in 
the file description entry in the Data 
Division. V-mode records may only be 
specified for standard sequential files. 
If the RECORDING MODE clause is omitted and 
BLOCK CONTAINS [integer-1 TO] integer-2... 
does not specify integer-2 less than the 
maximum level-01 record, the compiler 
determines the recording mode to be T if 
the file is standard sequential and one of 
the following conditions exists: 

• The FD entry contains two or more level 
01 descriptions of different lengths. 

• A record description contains an OCCURS 
clause with the DEPENDING ON option. 

• A RECORD CONTAINS clause specifies a 
range of record lengths. 

V-mode records, unlike U-mode or F-mode 
records, are preceded by fields containing 
control information. These control fields 
are illustrated in Figures 48 and 49. 

The first four bytes of each block 
contain control information (CC) : 

LL — represents two bytes designating 

the length of the block (including 
the 'CC' field) . 

BB -- represents two bytes reserved for 
system Use. 

The first four bytes of each logical 
record contain control information {cc) : 

11 — represents two bytes designating 
the logical record length 
(including the 'cc' field) . 

bb — represents two bytes reserved for 
system use. 

For unblocked V mode records (see Figure 
45) the data portion + CC + cc constitute 
the block . 
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VARIABLE-LENGTH RECORDS 
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There are two types of variable-length 
record: D-format and V-format. A D-format 
record is a variable-length record on an 
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Figure 48. Unblocked V-Mode Records 
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1st 
Logical Record 



2nd 
Logical Record 



3rd 
Logical Record 



I 1 1 1 1 1 1 1 1 1 r 

I LL I EB I 11 I bb I DATA-1 | 11 | bb | DATA-2 | 11 I bb | DATA-3 | 
I L_= 1 1— 1 1 1 1 1 I I r 




• CC » 

(block control 

bytes) 
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bytes) 
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For blocked V-mode records (see Figure 
U9) the data portion of each record + the 
cc of each record + CC constitute the 
block. 

The control bytes are automatically 
provided when the file is written and are 
not communicated to the programmer when the 
file is read. Although they do not appear 
in the description of the logical record 
provided by the programmer, the compiler 
will allocate input and output buffers 
which are large enough to accomodate them. 
When variable- length records are written on 
unit record devices, control bytes are 
neither printed nor punched. They appear, 
however, on other external storage devices 
as well as in buffer areas of storage. 
V-mode records moved from an input buffer 
to a working-storage area will be moved 
without the control bytes. 



The LABEL RECORDS clause is always 
required- The DATA RECORD (S) clause is 
never required. If the RECORDIi^G MODE 
clause is omitted, the compiler determines 
the mode as V since the record associated 
with VARIA3LE-FILE-1 varies in length 
depending on the contents of FIELD-B. The 
RECORD CONTAINS clause is never required. 
The compiler determines record sizes from 
the record description entries. Record 
length calculations are affected by the 
f ollowina: 



When the BLOCK CONTAINS clause with the 
RECORDS option is used, the compiler 
adds four oytes to the logical record 
length and four more bytes to the block 
length. 



Note : When a READ INTO statement is used 
for a V-mode file, the size of the longest 
record for that file is used in the MOVE 
statement. All other rules of the MOVE 
statement apply. 



Example 1 ; 

Consider the following standard 
sequential file consisting of unblocked 
V-mode records: 

FD VARIABLE-FILE-1 

RECORDING MODE IS V 

BLOCK CONTAINS 35 TO 8 CHARACTERS 
RECORD CONTAINS 27 TO 7 2 CHARACTERS 
DATA RECORD IS VARIABLE-RECORD- 1 
LABEL RECORDS ARE STANDARD. 

01 VARIABLE-RECORD-1. 

05 FIELD-A PIC X(20). 

05 FIELD-B PIC 99. 

05 FIELD-C OCCURS 1 TO 10 TIMES 



iJjit-JiiiilJ-'X 

FIELD-B 



NC 



PIC 9(5) 



• When the BLOCK CONTAINS clause with the 
CHARACTERS option is used, the 
programmer must include each cc + CC in 
the length calculation (see Figure U9). 
In the definition of VARIAELE-FILE-1, 
the BLOCK CONTAINS clause specifies 8 
more bytes than does the record 
contains clause. Four of these bytes 
are the logical record control bytes 
and the other four are the block 
control bytes. 



Assumming that FIELD-B contains the 
value 02 for the first record of a file and 
FIELD-B contains the value 03 for the 
second record of the file, the first two 
records will appear on an external storage 
device and in buffer areas of storage as 
shown in Figure 50. 



If the file described in Example 1 had a 
blocking factor of 2, the first two records 
would appear on an external storage medium 
as shown in Fiaure 51. 



i 
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1st Block 



2nd Block 



T 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 

I 0040 I BB I 0036 | bb | FIELD-A | 02 | FIELD-C | FIELD-C | 0045 | BE | 004 1 1 bb | FIELD-A | 03 | FIELD-C | FIELD-C | FIELD-C | 

I t I I I « ■ I I ■ ■ l___l L__J I I I 



Note : Lengths appear in decimal notation for illustrative purposes, 



Figure 50. Fields in Unblocked V-Mode Records 



1st Record 



2nd Record 



r ——--I r—~ 1 1 1 1 1 1 1 1 1 1 1 1 1 

I 0081 I BB I 0036 I bb I FIELD-A I 02 I FIELD-C I FIELD-C I 0041 1 bb I FIELD-A I 03 I FIELD-C I FIELD-C I FIELB-C I 

I I ! I I 1 I I I 1 1 1 1 1 1 1 

Note: Lengths appear in decimal notation for illustrative purposes. 
Figure 51. Fields in Blocked V-Mode Records 



Example 2 : 

If VARIABLE-FILE-2 is blocked, with 
space allocated for three records of 
maximum size per block, the following FD 
entry could be used when the file is 
created : 



FD VARIABLE-FILE-2 

RECORDING MODE IS V 

BLOCK CONTAINS 3 RECORDS 

RECORD CONTAINS 20 TO 100 CHARACTERS 

DATA RECORDS ARE VARIABLE-RECORD-1 , 

VARIABLE-RECORD-2 

LABEL RECORDS ARE STANDARD. 

01 VARIABLE-RBCORD-1. 

05 FIELD-A PIC X (20) . 
05 FIELD-B PIC X (80) . 

01 VARIABLE-RECORD-2. 

05 FIELD-X PIC X(20) . 

As mentioned previously, the RECORDING 
MODE, RECORD CONTAINS, and DATA RECORDS 
clauses are unnecessary. By specifying 



that each block contains three records, the 
programmer allows the compiler to provide 
space for three records of maximum size 
plus additional space for the required 
control bytes. Hence, 316 character 
positions are reserved by the compiler for 
each output buffer. If this size is other 
than the maximum, the BLOCK CONTAINS clause 
with the CHARACTERS option should be 
specified. 

Assuming that the first six records 
written are five 100-character records 
followed by one 20-character record, the 
first two blocks of VARIABLE-FILE-2 will 
appear on the external storage device as 
shown in Figure 52. 

The buffer for the second block is 
truncated after the sixth WRITE statement 
is executed since there is not enough space 
left for a maximum size record. Hence, 
even if the seventh WRITE to 
VARIABLE-FILE-2 is a 20-character record, 
it will appear as the first record in the 
third block. This situation can be avoided 
by using the APPLY WRITE-ONLY clause when 
creating files of variable-length blocked 
records . 



182 



1st Block 



2nd Block 



I 1 1 1 1 1 1 1 1 1 1 r 

I 316 I BB 1 10it|bb|Datai 104 |bb|Datat 104 |bb|Data| 



I 236 I BB I 10 4 I bb I Data I 104 |bb | Data 1 24 |bb 1 Data | 



Note: Lengths appear in decimal notation for illustrative purposes. 



Figure 52. First Two Blocks of VAEIABLE-FILE-2 



APPLY WRITE-ONLY Clause 



The APPLY HEITE-ONLY clause is used to 
make optimum use of buffer and external 
storage space when creating a standard 
sequential file with blocked V-mode 
records. 

Suppose VAEIABLE-FILE-2 is being created 
with the following FD entry: 



Note: When using the APPLY WRITE-ONLY 
clause, records must not be constructed in 
buffer areas. An intermediate work area 
must be used with a WRITE FPOH statement. 

If an APPLY WRITE-ONLY clause is specified 
for a file and an OCCURS DEPENDING ON clause 
is specified within a record description of 
the file, the object of the OCCURS DEPENDING 
ON clause should not be defined within the 
record description for the file. 



FD VARIABLE-FILE-2 

RECORDING MODE IS V 

BLOCK CONTAINS 316 CHARACTERS 

RECORD CONTAINS 20 TO 100 CHARACTERS 

DATA RECORDS ARE VARIABLE-RECORD-1 , 

VARIABLE-RECORD-2 

LABEL RECORDS ARE STANDARD. 

01 VARIABLE-RECORD-1. 

05 FIELD-A PIC X (20) . 
05 FIELD-B PIC X (80) . 

01 VARIABLE-RECORD-2. 

05 FIELD-X PIC X (20) . 

The first three WRITE statements to the 
file create one 20-character record 
followed by two 100-character records. 
Without the APPLY WRITE-ONLY clause, the 
buffer is truncated after the third WRITE 
statement is executed, since the maximum 
size record no longer fits. The block is 
written as shown below: 



I 1 1 1 1 1 1 1 1 1 1 1 

I 236 I bb I 24 I bb I Data 1 104 | bb | Data 1 104 | bb | Data | 



Using the APPLY WRITE-ONLY clause will 
cause a buffer to be truncated only when 
the next record does not fit in the buffer. 
That is, if the next three WRITE statements 
to the file specify VARIABLE-RECORD-2, the 
block will be created containing six 
logical records, as shown below: 

I 1 1 1 1 1 1 1 1 1 1 X 

I 308 1 bb I 24 I bb I Data 1 104 | bb | Data | 104 | bb | Data ^ 



SPANNED (FORHAT S) RECORDS 



A spanned record is a logical record 
that may be contained in one or more 
physical blocks. Format S records may be 
specified for direct files and for standard 
seguential files assigned to magnetic tape 
or to mass storage devices. 

When creating files with S-mode records, 
if a record is larger than the remaining 
space in a block, a segment of the record 
is written to fill the block. The 
remainder of the record is stored in the 
next block or blocks, as required. 

When retrieving a file with S-mode 
records, only complete records are made 
available to the programmer. 

Spanned records are preceded by fields 
containing control information. Figure 53 
illustrates the control fields. 



BDF (Block Descriptor Field) : 

LL — represents 2 bytes designating the 
length of the physical block 
(including the block descriptor 
field itself) . 

BB — represents 2 bytes reserved for 
system use. 
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1 1 1 1 1 1 1 1 1 

24 I bb I Data | 24 1 bb | Data 1 24 | bb | Data | 
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SDF (Segment Descriptor Field) : 

11 — represents 2 bytes designating the 
length of the record segment 
(including the segment descriptor 
field itself) . 

bb — represents 2 bytes reserved for 
system use . 



Figure 54 is an illustration of blocked 
spanned records of SFILE. SFILE is 
described in the Data Division with the 
following file description entry: 

FD SFILE 

RECORD CONTAINS 250 CHflEACTEBS 
BLOCK CONTAINS 100 CHARACTERS 



Note : There is only one block descriptor 
field at the beginning of each physical 
block. There is, however, one segment 
descriptor field for each record segment 
within the block. 

Each segment of a record in a block, 
even if it is the entire record, is 
preceded by a segment descriptor field. 
The segment descriptor field also indicates 
whether the segment is the first, the last, 
or an intermediate segment. Each block 
includes a block descriptor field. These 
fields are not described in the Data 
Division; provision is automatically made 
for them. These fields are not available 
to the programmer. 

A spanned blocked file may be described 
as a file composed of physical blocks of 
fixed length established by the programmer. 
The logical records may be either fixed or 
variable in length and that size may be 
smaller, egual to, or larger than the 
physical block size. There are no required 
relationships between logical records and 
physical block sizes. 

A spanned unblocked file may be 
described as a file composed of physical 
blocks each containing one logical record 
or one segment of a logical record. The 
logical records may be either fixed or 
variable in length. When the physical 
block contains one logical record, the 
length of the block is determined by the 
logical record size. When a logical record 
has to be segmented, the system always 
writes the largest physical block possible. 
The system segments the logical record when 
the entire logical record cannot fit on the 
track. 



Figure 54 also illustrates the concept 
of record segments. Note that the third 
block contains the last 50 bytes of EEC-1 
and the first 50 bytes of REC-2. Such 
portions of logical records are called 
record segments. It is therefore correct 
to say that the third block contains the 
last segment of REC-1 and the first segment 
of REC-2. The first block contains the 
first segment of EEC-1 and the second block 
contains an intermediate segment of REC-1. 



S-HODE CAPABILITIES 



Formatting a file in the S-mode allows 
the programmer to make the most efficient 
use of external storage while organizing 
data files with logical record lengths most 
suited to his needs. 

1. Physical record lengths can be 
designated in such a manner as to make 
the most efficient use of track 
capacities on mass storage devices. 

2. The programmer is not required to 
adjust logical record lengths to 
maximum physical record lengths and 
their device-dependent variants when 
designing his data files. 

3. The programmer has greater flexibility 
in transferring logical records across 
DASD types. 

Spanned record processing will support 
the 2400, 3410, 3420 tape series, the 2311, 
2314, 2319, 3330, and 3340 disk storage 
devices, and the 2321 data cell drive. 



< — 4 bytes > < — 4 bytes — > <- 



-Variable bytes- 
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Figure 53. Control Fields of an S-Mode Record 
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< 100 bytes- > < 100 bytes > <-50 bytes-> <-50 bytes-> 



REC-1 



1st Block 



I G I 



REC-1 



2nd Block 



I G I 



REC-1 



REC-2 



3rd Block 



Figure 54. One Logical Record Spanning Physical Blocks 



SEQUENTIALLY ORGANIZED S-MODE FILES ON TAPE 



UK nRZ>^ axuriiitoii DEixL^b 



When the spanned format is used for 
DTFMT or DTFSD files, the logical records 
may be either fixed or variable in length 
and are completely independent of physical 
record length. A logical record may span 
physical records. A physical record may 
contain one or more logical records and/or 
segments of logical records. 



When the spanned recording mode is being 
used, each logical record is processed in a 
work area, not in the buffer. Logical 
records are always aligned on a double-word 
boundary. Therefore, the programmer is not 
reguired to add inter-record slack bytes 
for alignment purposes. 

Except for the APPLY WRITE-ONLY clause, 
all the options for a variable file apply 
to a spanned file. 



Source Language Considerations 



The programmer specifies S-mode by 
describing the file with the following 
clauses in the file description (FD) entry 
of his COBOL program: 



Processing Seguentially Organized 3-Hode 
Files 



Suppose a file has the following file 
description entry: 



• BLOCK CONTAINS integer-2 CHARACTERS 

• RECORD CONTAINS [integer-1 TO] 
integer-2 CHARACTERS 



FD SPAN-FILE 

BLOCK CONTAINS 100 CHARACTERS 
LABEL RECORDS ARE STANDARD 
DATA RECORD IS DATAREC. 



• RECORDING HODE IS S 

The size of the physical record must be 
specified using the BLOCK CONTAINS clause 
with the CHARACTERS option. Any block size 
may be specified. Block size is 
independent of logical record size. 

The size of the logical record may be 
specified by the RECORD CONTAINS clause. 
If this clause is omitted, the compiler 
will determine the maximum record size from 
the record descriptions under the FD. 

Format S may be specified by the 
RECORDING MODE IS S clause. If this clause 
is omitted, the compiler will set the 
recording mode to S if the BLOCK CONTAINS 
integer-2 CHARACTERS clause was specified 
and either: 

1 . integer-2 is less than the largest 
fixed-length level-01 FD entry 

2* integer-2 is less than the maximum 

length of a variable level-01 FD entry 
(i.e., an entry containing one or more 
OCCURS clauses with the DEPENDING ON 
option) . 



01 DATAREC. 

05 FIELD-A PIC X (100) . 
05 FIELD-B PIC X (50) . 

Figure 55 illustrates the first four 
blocks of SPAN-FILE as they would appear on 
external storage devices (i.e., tape or 
mass storage) or in buffer areas of virtual 
storage. 



Note 



2. 



3. 



The RECORDING MODE clause is not 
specified. The compiler determines 
the recording mode to be S since the 
block size is less than the record 
size . 

The length of each physical block is 
100 bytes, as specified in the BLOCK 
CONTAINS clause. All reguired control 
fields, as well as data, must be 
contained within these 100 bytes. 

No provision is made for the control 
fields within the level-01 entry 
DATAREC. 
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Figure 55. First Four Blocks of SPAN-FILE 
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Note : The enclosed diagrams are for illustrative purposes only. Neither takes into 
account the space reguired for control fields. 



Figure 56. Advantage of S-Sode Records Over V-Hode Records 



The preceding discussion dealt with 
S-mode records which were larger than the 
physical blocks that contained them. It is 
also possible to have S-mode records which 
are egual to or smaller than the physical 
blocks that contain them. In such cases, 
the RECORDING MODE clause must specify S 
(if so desired) since the compiler cannot 
determine this by comparing block size and 
record size. 



For V-mode records, buffers are 
truncated if the next logical record is too 
large to be completely contained in the 
block (see Figure j6) . This results in 
more physical blocks <ind more inter-record 
gaps on the external storage device. 



Note: For V-mode records, buffer 
truncation occurs: 



One advantage of S-mode records over 
V-mode records is illustrated by a file 
with the following characteristics: 

1. RECORD CONTAINS 50 TO 150 CHARACTERS 

2. BLOCK CONTAINS 350 CHARACTERS 

3. The first five records written are 
150, 150, 150, 100, and 150 characters 
in length. 



1. When the maximum level-01 record is 
too large. 

2. If APPLY WRITE-ONLY or SAME RECORD 
AREA is specified and the actual 
logical record is too large. 

For S-mode records, all blocks are 350 
bytes long and records that are too large 
to fit entirely into a block will be 
segmented. This results in more efficient 
use of external storage devices since the 
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number of inter-record gaps are minimized 
(Figure 56) . 



With the exception of the last block, 
the actual physical block size will always 
fall between the limits of specified block 
size and four bytes less than the specified 
block size, depending on whether or not the 
residual space of an incomplete block in 
the buffer is sufficient to add a segment 
length field and at least one byte of data. 
That is, specified block size - 4 < actual 



DIRECTLY OBGANIZED S-MODE FILES 



When S-mode is used for a directly 
organized file, only unblocked records are 
permitted. Logical records may be either 
fixed or variable in length. A logical 
record will span physical records if, and 
only if, it spans tracks. A physical 
record will contain only one logical record 
or a segment of a logical record, or 
segments of two logical records and/or 
whole logical records. Records may span 
tracks,, cylinders ; and extents, but not 
volumes. 



The last block may be short when an 
incomplete block remains in the buffer at 
CLOSE time. 



Source Language Considerations 



A second advantage of S-mode processing 
over that of V-mode is that the programmer 
is no longer limited to a record length 
that does not exceed the track capacity of 
the mass storage device selected. Records 
may span track, cylinders, and extents, but 
not volumes. 

DTFMT and DTFSD spanned records differ 
from other formats because of an allocation 
of an area of storage known as the "logical 
record area." If logical records span 
physical blocks, COBOL will use this 
logical record area to assemble complete 
logical records. If logical records do not 
span blocks {i.e., they are contained 
within a single physical block) the logical 
record area is not used. Regardless, it is 
complete logical records that are made 
available to the programmer. Both READ and 
WRITE statements should be thought of as 
manipulating complete logical records and 
not record segments. 



The programmer specifies S-mode by 
describing the file with the following 
clauses in the file description (FD) entry 
of his COBOL program; 

• BLOCK CONTAINS integer-2 CHARACTERS 

• RECORD CONTAINS [ integer-1 TO] integer-2 

CHARACTERS 

• RECORDING MODE IS S 

The size of a logical record may be 
specified by the RECORD CONTAINS clause. 
If this clause is omitted, the compiler 
will determine the maximum record size from 
the record descriptions under the FD. 

The spanned format may be specified by 
the RECORDING HODE IS S clause. If this 
clause is omitted, the compiler will set 
the recording mode to S if the BLOCK 
CONTAINS integer-2 CHARACTERS clause was 
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Figure 57. Direct and Sequential Spanned Files on a Mass Storage Device 
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specified and integer-2 is less than the 
greatest logical record size. This is the 
only use of the BLOCK CONTAINS clause. It 
is otherwise treated as comments. 

The physical block size is determined by 
either: 



one logical record or one record segment. 
Logical record R3 spans physical blocks 
only because it spans tracks. The file 
consists of seven physical blocks, occupies 
more than three tracks, and contains three 
inter-record gaps. 



1. The logical record length, or 

2. The track capacity of the device being 
used. 

If, for example, the track capacity of a 
mass storage device is 3625 characters, any 
record smaller than 3625 characters may be 
written as a single physical block. If a 
logical record is greater than 3625 
characters, the record is segmented. The 
first segment may be contained in a 
physical block of up to 3625 bytes, and the 
remaining segments must be contained in 
succeeding blocks. In other words, a 
logical record will span physical blocks 
if, any only if, it spans tracks. 

Figure 57 illustrates four 
variable-length records (El, R2, R3, and 
R4) as they would appear in direct and 
sequential files on a mass storage device. 
In both cases, control fields have been 
omitted for illustrative purposes. For 
both files, assume: 

1. BLOCK CONTAINS 3625 CEARACTERS (track 
capacity = 3625) 

2. RECORD CONTAINS 500 TO 5000 CHARACTERS 

In the sequential file, each physical 
block is 3625 bytes in length and is 
completely filled with logical records. 
The file consists of three physical blocks, 
occupies three tracks, and contains no 
inter-record gaps. 

In the direct file, the physical blocks 
vary in length. Each block contains only 



Processing Directly Organized S-Hode Files 



When processing directly organized 
files, there are two advantages spanned 
format has over the other record formats: 

1 . Logical record lengths may exceed the 
length restriction of the track 
capacity of the mass storage device. 
If, for example, the track capacity of 
a mass storage device is 2000 bytes, 
the length of each logical record for 
formats other than spanned is, by 
necessity, restricted to the track 
capacity. 

Note: Even when the spanned format is 
used, the COBOL restriction on the 
length of logical records (i.e., a 
maximum length of 32,767 characters) 
must be adhered to. 

2. For formats other than spanned, only 
complete logical records can be 
written on any single track. This 
means that if a track has only 1000 
unoccupied bytes and the programmer 
attempts to add a record of 1100 bytes 
to this track, an INVALID KEY 
condition will occur. When the 
spanned format is used, a 1000 byte 
segment will be written on the 
specified track, and the remainder 
will be written on the next track. 
The segmenting is transparent to the 
programmer. 
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PART III 



PROGRAMMING TECHNIQUES 



USING THE SORT FEATURE 



USING THE REPORT WRITER FEATURE 



i 
i 
i 



TABLE HANDLING CONSIDERATIONS' 
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PROGRAMFiING TECHNIQUES 



This chapter describes techniques and 
hints for better COBOL programming. 



CODING CONSIDERATIONS FOR DOS/VS 



These suggestions will aid DOS/VS 
efficiency: 

• If a short subprogram is referenced 
only once or twice (and is not an 
exception condition routine) , then its 
code should be incorporated in the 
calling program, if convenient. 

• Subprograms and frequently used 
subroutines should be loaded near the 
programs which use them. This can be 
done via linkage editor control cards. 

• Segmentation in many cases is no longer 
necessary or desirable. 

• Data items of constant value should be 
grouped together. Data items whose 
values vary during execution should 
also be grouped together and should be 
separate from those of constant value, 
if feasible. 

• FDs for files that will be opened at 
the same time should be grouped 
together. 

• The most frequently referenced data 
items should be placed in the beginning 
of the Working Storage Section. 

• The COBOL Procedure Division should be 
organized generally as follows: 

- All frequently used paragraphs or 
sections should be located near the 
routines that use them. 



N ote : When OPT is in effect, the 
generated code is more suitable for 
running under VS, as the addressing 
scheme is designed to reduce possible 
page faults. 

Further, the procedure is divided into 
UK blocks, each of which is assicfned a 
PBL. Since these blocks correspond to 
two pages each, the user may get some 
idea of the inter-page relationships in 
his program (although the first is not 
page aligned) . The statement range for 
each PBL is given on the compiler 
output listing. This should help the 
user rearrange his program if he so 
desires. 

The REDEFINES clause should be used for 
its alternate grouping and alternate 
description capabilities rather than 
for merely saving space. Although it 
will save virtual space, it can lead to 
coding errors if not used carefully. 



GENERAL CONSIDERATIONS 



^ 



COPY 



The COPY function should be used by an 
installation so that if a record format, 
for example, changes, each program does not 
need to be modified itself. Rather, the 
COPY library is updated and each program 
then recompiled. 

Use of this function can lead to 
standardization of naming conventions and 
ease of maintenance. 



SYNTAX CHECKING 



- All infrequently used paragraphs or 
sections should be grouped together 
and apart from frequently used 
routines. The COUNT option can be 
used as an aid in this process. 

• Avoid initializing data areas until 
just before they are needed. 

• Reference data in the order in which it 
is stored. 

• Use the OPTIMIZE feature if possible. 



The first several compilations of a 
program should use the CSYNTAX or SYNTAX 
feature to save compilation time. 



Formatting the Source Program Listing 



The lister feature increases 
significantly the usability of the source 
program listing, not only by producing 
cross-reference inforitiation, but by 
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formatting the listing to aid logic 
tracing. There are four statements that 
can be coded in any or all of the four 
divisions of a source program: SKIPl, 
SKIP2, SKIP3, and EJECT. These statements 
provide the programmer with the ability to 
control the spacing of a source listing and 
thereby improve its readability. These 
statements should not be used when the 
lister feature is used. 



ENVIRONMENT DIVISION 



RESERVE Clause 



When using an additional buffer to 
process standard sequential or indexed 



files, care must be taken to ensure that 
the buffer is filled before the execution 
of each WRITE or REWRITE Statement. 



APPLY WRITE-ONLY Clause 



To make optimum use of buffer and 
external storage space allocated when 
creating a standard sequential file with 
blocked V-mode records, the programmer 
should use the APPLY WRITE-ONLY clause for 
the file. Using this clause causes a 
buffer to be truncated only when the next 
record does not fit in the buffer. (If 
APPLY WRITE-ONLY is not specified, the 
buffer is truncated when the maximum size 
record will not fit in the space remaining 
in the buffer. ) 
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DATA DIVISION 



STORAGE CONSIDERATIONS 



"corresponding" names with the prefixed 
unique names. This technique eliminates 
excessive qualifying. For example: 



The amount of storage used for all FD 
entries, the WORKING STORAGE SECTION, and 
REPORT SECTION must not exceed 1 Mb, since 
the compiler can only handle a maximum of 
255 for BL-CELLS. One BL-CELL is assigned 
for each file or for 4096, whichever 
comes first. 

OVERALL CONSIDERATIONS 
FD Entries 

File Description (FD) entries for the 
most active files should appear first, 
since the COBOL compiler assigns registers 
to files until it runs out of registers, 
and then reuses the last registers for all 
subsequent files. This does not apply when 
OPT is in effect, since in that case the 
compiler will determine the frequency of 
usage and assign registers accordingly. 

Prefixes 



01 



M ST- WORK- AREA. 

05 SAME- NAMES- (***) 

10 LAST-NAME PIC... 

10 FIRST-NAME PIC. 

10 PAYROLL PIC 



05 DIFF-NAMES REDEFINES SAME-NAMES, 



MST= LAST-NAME 



PTr . 



01 



10 MST-FIRST-NAME PIC. 

10 MST-PAYROLL PIC 

RPT- WORK- AREA. 

05 SAME- NAMES. (**+) 

10 PAYROLL PIC... 

10 FILLER PIC... 

10 FIRST-NAME PIC 

10 FILLER PIC... 

10 LAST- NAME PIC... 



PROCEDURE DIVISION, 




Assign a prefix to each level-01 item in 
a program, and use this prefix on every 
subordinate item (except FILLER) to 
associate a file with its records and work 
areas. For example, MASTER is the prefix 
used here: 



IF MST-PAYROLL IS EQUAL TO HDQ-PAYROLL 

AND MST- LAST- NAME 

IS NOT EQUAL TO PRRV-LAST-NAME 

MOVE CORRESPONDING 

MST- WORK- AREA 

TO RPT- WORK- AREA. 



FILE SECTION. 

FD MASTER-INPUT-FILE 



01 MASTER- INPUT-RECORD. 



Note: Fields marked *** above m.ust have 
exactly the same names for their 
subordinate fields to be considered 
"corresponding." The same names must not 
be the redefining ones or they will not be 
considered to correspond. 



WORKING- STORAGE SECTION. 
01 MASTER- WORK- AREA. 

05 MASTER- PAYROLL PICTURE 9(3). 

05 MASTER-SSNO PICTURE 9(9). 

If files or work areas have the same 
fields, use the prefix to distinguish 
between them. For example, if three files 
all have a date field, instead of DATE, 
DAT, and DA-TE, use MASTER-DATE, 
DETAIL-DATE, and REPORT-DATE. Using a 
unique prefix for each level-01 item and 
all subordinate fields makes it easier for 
a programmer unfamiliar with the program to 
find fields in the program listing, and to 
know which fields are logically part of the 
same record or area. 

When using the MOVE statement with the 
CORRESPONDING Option and referring to 
individual fields, redefine or rename 



Level Numbers 



The programmer should use widely 
incremented level numbers such as 01, 05, 
10, 15, etc., instead of 01, 02, 03, 04, 
etc. , in order to allow space for future 
insertions of group levels. For 
readability, indent level numbers. (The 
lister feature does this automatically, 
even if the original source program does 
not follow such indenting practices.) 

Note that when using the SYMDMP option, 
level numbers appear "normalized" in the 
symbolic dump produced. For example, a 
group of data items described as: 

01 RECORDA. 

05 FIELD-A. 

10 FIELD-Al PIC X. 
10 FIELD-A2 PIC X. 
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will appear as follows in SYMDMP output; 

01 RECORDA.. . 

02 FIELD-A... 

03 FIELD-Al 

03 FIELD-A2, . . 

Use level number 88 for codes. Thus, if 
the codes must be changed, the Procedure 
Division coding for tests need not be 
changed. 



2, Areas which do not contain VALUE 
clauses should be separated from areas 
that do contain VALUE clauses. VALUE 
clauses (except for level-88 items) 
are invalid in the Linkage Section. 

3. When the Working- Storage Section 
consists of one level-01 item without 
any VALUE clauses, the COPY statement 
can easily be used to include the item 
as the description of a Linkage 
Section in a separately compiled 
module. 



FILE SECTION 



RECORD CONTAINS Clause 



4. See the chapter "Using the 

Segmentation Feature" for information 
on how to miodularize the Procedure 
Division of a COBOL program; VS coding 
considerations should also be taken 
into account. 



The programmer should use the RECORD 
CONTAINS clause with the integer CHARACTERS 
option in order to save himself, as well as 
any future programmer, the task of counting 
the data record description positions. In 
addition, the compiler can then diagnose 
errors if the data record description 
conflicts with the RECORD CONTAINS clause. 



BLOCK CONTAINS Clause 



If a block prefix exists on an ASCII 
file and the BLOCK CONTAINS clause is used 
in the COBOL program, the length of the 
block prefix must be included in the BLOCK 
CONTAINS clause- 



Locating the Working-Storage Section in 
Dumps 



If the SYMDMP option is not used for 
program debugging, a method of locating the 
Working-Storage Section of a program in 
object-time dumps is to include the two 
following statements as the first and last 
Working-Storage statements, respectively, 
in the program. 

77 FILLER PICTURE X(4a), VALUE "PROGRAM 

XXXXXXXX WORKING- STORAGE BEGINS HERE". 

01 FILLER PICTURE X(42), VALUE "PROGRAM 
XXXXXXXX WORKING-STORAGE ENDS HERE". 



WORKING- STORAGE SECTION 



Separate Modules 



In a large program, the programmer may 
wish to plan ahead for breaking the 
programs into separately compiled modules, 
as follows: 



These two nonnumeric literals will 
appear in all dumps of the program, 
delimiting the Working-Storage Section. 
The program-name specified in the 
PROGRAM-ID clause should replace the 
XXXXXXXX in the literal. 

The location and length of 
Working- Storage is given in the compiler 
output when SYM, LISTX, or CLIST is in 
effect. 



When using separate modules, an 
attempt should be made to combine 
entries of each Working-Storage 
Section into a single level-01 record 
(or a single level-01 record for each 
32K bytes) . Logical record areas can 
be indicated by using level-02, -03, 
etc., entries. A CALL statement with 
the USING option is more efficient 
when a single item is passed than when 
many level-01 and/or -77 items are 
passed. When this method is employed, 
mistakes are more easily avoided. 



REDEFINES Clause 



REUSING DATA AREAS : Virtual storage can be 
used more efficiently by writing different 
data descriptions for the same data area. 
For example, the coding that follows shows 
how the same area can be used as a work 
area for the records of several input files 
that are not processed concurrently. 
Caution should be exercised when using this 
procedure, as it can lead to programming 
errors. 
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WORKING-STORAGE SECTION. 
01 W0RK-AREA-FILE1. 

(largest record description for FILEI) 



The following illustrates how a table 
(TABLEA) can be initialized by having 
different data descriptions for the same 
data: 



01 W0RK-AREA-FILE2 REDEFINES 
WORK-AREA-FILEI. 
(largest record description for FILE2) 



ALTERNATE GR0DPIN6S AND DESCRIPTIONS : 
Program data can often be described more 
efficiently by providing alternate 
groupings or data descriptions for the same 
data. For example, a program references 
both a field and its subfields, each of 
which is more efficiently described with a 
different usage. This can be done by using 
the REDEFINES clause as follows: 



01 
05 
05 



05 



PAYROLL-RECORD. 

EHPLOYEE-RECORD PICTURE X (28) . 

EBPLOYEE-FIELD REDEFINES 

EMPLOYEE-RECORD. 

10 NAME PICTURE X (24) . 

10 NUMBERX PICTDRE S9 (5) COMP. 

DATE-RECORD PICTDRE X (10) . 



05 VALUE-A. 

10 A1 PICTDRE S9 (9) COMPUTATIONAL 

VALUE IS ZEROES. 
10 A2 PICTURE S9 (9) COMPUTATIONAL 

VALUE IS 1. 



10 A100 PICTURE S9 (9) COMPUTATIONAL 
VALUE IS 99. 
05 TABLEA REDEFINES VALUE-A 

PICTURE S9 (9) COMPUTATIONAL 
OCCURS 100 TIMES. 



Note: Caution should be exercised when 
redefining a subscript. If the value of 
the redefining data item is changed in the 

Procedure Division, a new calculation for 
the subscript is performed only if a new 
paragraph is entered. 
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PICTDRE Clause 

DECIKAL-POINT ALIGNMENT : Procedure 
Division operations are most efficient when 
the decimal positions of the data items 
involved are aligned. If they are not, the 
compiler generates instructions to align 
the decimal positions before any operations 
involving the data items can be executed. 
This is referred to as scaling. 

Assume, for example, that a program 
contains the following instructions: 

WORKING-STORAGE SECTION. 
77 A PICTURE S999V99. 
77 B PICTDRE S99V9. 



PROCEDDRE DIVISION. 



ADD A TO B. 

Time and internal storage space are 
saved by defining B as: 

77 B PICTURE S99V99. 

If it is inefficient to define B 
differently, a one-time conversion can be 
done, as explained in "Data Format 
Conversion" in this chapter. 

FIELDS OF UNEQUAL LENGTH : When a data item 
is moved to another data item of a 
different length, the following should be 
considered : 

• If the items are external decimal 
items, the compiler generates 
instructions to insert zeros in the 
high-order positions of the receiving 
field, when it is the larger. 

• If the items are nonnumeric, the 
compiler may generate instructions to 
insert spaces in the low-order 
positions of the receiving field (or 
the high-order positions if the 
JUSTIFIED RIGHT clause is specified) . 
This generation of extra instructions 
can be avoided if the sending field is 
described with a length equal to or 
greater than the receiving field. 

SIGN USAGE ; The presence or absence of a 
plus or minus sign in the description of an 
arithmetic field often can affect the 
efficiency of a program. The following 
paragraphs discuss some of the 
considerations . 

Decimal Items : The sign position in an 
internal or external decimal item can 
contain: 



1. A plus or minus sign. If S is 
specified in the PICTDRE clause, a 
plus or minus sign is inserted when 
either of the following conditions 
prevail: 

a. The item is in the Working-Storage 
Section and a VALDE clause has 
been specified. 

b. A value for the item is assigned 
as a result of an arithmetic 
operation during execution of the 
program. 

If an external decimal item is 
punched, printed, or displayed, an 
overpunch will appear in the low-order 
digit. In EBCDIC, the configuration 
for low-order zeros normally is a 
nonprintable character. Low-order 
digits of positive values will be 
represented by one of the letters A 
through I (digits 1 through 9) ; 
low-order digits of negative values 
will be represented by one of the 
letters J through R (digits 1 through 
9) . 

2. A hexadecimal F. If S is not 
specified in the PICTDRE clause, an F 
is inserted in the sign position when 
either of the following conditions 
prevail: 

a. The item is in the Working-Storage 
Section and a VALUE clause has 
been specified 

b. A value for the item is developed 
during the execution of the 
program . 

An F is treated as positive, but is 
not an overpunch. 



3. An invalid configuration. If an 
internal or external decimal item 
contains an invalid configuration in 
the sign position, and if the item is 
involved in a Procedure Division 
operation, the program will be 
abnormally terminated. 

Note : If the SIGN clause is used and it 
specifies that the sign is LEADING, more 
object code will be generated when that 
data item is used with a verb. The 
additional code is needed to move the sign 
character to the TRAILING position before 
Derformina the operation^ 



Unsigned items (items for which no S has 
been specified) are treated as absolute i 
values. Whenever a value (signed or I 
unsigned) is stored in or moved in an 
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elementary move to an unsigned item, a 
hexadecimal F is stored in the sign 
position of the unsigned item. For 
example, if an arithmetic operation 
involves signed operands and an unsigned 
result field, compiler-generated code will 
insert an F in the sign position of the 
result field when the result is stored. 



For internal and external decimal items 
used as input, it is the programmer's 
responsibility to ensure that the input 
data is valid. The compiler does not 
generate a test to ensure that the 
configuration in the sign position is 
valid. 



When a group item is being moved, the 
data is moved without regard to the level 
structure of the group items involved. The 
possibility exists that the configuration 
in the sign position of a subordinate 
numeric item may be destroyed. Therefore, 
caution should be exercised in moving group 
items with subordinate numeric fields or 
with other group operations such as READ or 
ACCEPT. 



OSAGE Clause 



DATA FORHAT CONYEESION : Operat 
involving mixed, elementary num 
formats reguire conversion to a 
format. This usually means tha 
storage is used and execution t 
increased. The code generated 
move data to an internal work a 
any necessary conversion, and t 
the indicated operation. Often 
result may have to be converted 
way. Table 31 indicates when d 
conversion is necessary. 



ions 
eric data 

common 
t additional 
ime is 
must often 
rea, perform 
hen execute 
, too, the 

in the same 
ata 



i 



If it is impractical to use the same 
data formats throughout a program, and if 
two data items of different formats are 
frequently used together, a one-time 
conversion can be effected. For example, 
if A is defined as a COMPUTATIONAL item and 
B as a COMPUTATION AL-3 item, A can be moved 
to a work area that has been defined as 
COMPUTATTONAL-3. This move causes the data 
in A to be converted to COMPUTATIONAL-3. 
Whenever A and B are used in a Procedure 
Division operation, reference can be made 
to the work area rather than to A. When 
this technique is used, the conversion is 
performed only once, instead of each time 
an operation is performed. 
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Table 31. Data Format Conversion (Part 1 of 2) 



1 1 




— — 1 

Boundary 




.... ,„. -. , , 

Converted 
for 


r— - - "" -1 




Bytes 


Alignment 


Typical 


Arithmetic 


Special 1 


1 Usage 


Required 


Required 


Usage 


Operations 


Characteristics f 


[DISPLAY 


1 per digit 


No 


Input from 


Yes 


May be used for numeric | 


1 (external 


(except for 




cards, output 




fields up to 18 digits | 


I decimal) 


V) 




to cards, 
listings 




long. 1 

Fields over 15 digits | 
require extra instruc- | 
tions if used in | 
computations. | 


IDISPLAY 


1 per 


No 


Input from 


Yes 


Converted to COHP-2 j 


1 (external 


character 




cards, output 




format via COBOL library | 


1 floating 


(except for 




to cards. 




subroutine. | 


1 point) 


V) 




listings 


1 i 

1 1 


ICOHP-3 


1 per 2 


No 


Input to a 


Sometimes 


1 
Requires less space than | 


1 (internal 


digits plus 




report item 


when a 


DISPLAY. 1 


1 decimal) 


1 byte for 






small 






low-order 




Arithmetic 


COMP-3 item 


Convenient form for | 




digit and 




fields 


is used 


decimal alignment. | 




sign 






with a 










Work areas 


small COMP 
item 


Can be used in arithmetic! 
computations without | 
conversion. | 

Fields over 15 digits | 
require a subroutine when] 
used in computations. | 


ICOMP 


2 if 1<N<U 


Halfword 


Subscripting 


Sometimes 


Rounding and testing for | 


1 (binary) 








for both 


the ON SIZE ERROR | 




4 if 5<N<9 


Fullword 


Arithmetic 


mixed and 


condition are cumbersome j 








fields 


unmixed 


if calculated result is | 




8 if 10<H<18 


Pullword 




usages 


greater than 9 (9) . | 




where N is 












the number of 








Extra instructions are | 




9»s in the 








generated for computa- | 




picture 








tions if the SYNCHRONIZED! 
clause is not specified. ! 

Fields of over nine | 
digits require additional! 
handling. | 
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Table 31. Data Format Conversion (Part 2 of 2) 



1 1 ■ -r — ■ - '■'- r - ,..,...... ._.. .^. . -.., ,.,, _. _ , 

1 1 1 1 1 Converted | I 
1 1 IBountary | | for | I 
1 1 Bytes 1 Alignment! Typical [Arithmetic | Special | 
1 Usage | Required [Required | Usage | Operations | Characteristics | 


1 COHP-1 |4 (short- I Full word | Fractional | No | Tends to produce less | 
1 (internal 1 precision)! [exponentiation! | accurate results if more ! 
! floating! ! ! j | than 17 significant | 

I point) ! II 1 ! digits are required and | 
! ! ! 1 1 1 if the exponent is ! 

II 11 II large. I 

I 1 II II Extra instructions are | 

II 11 II generated for computa- | 
II i ! ! 1 tions if the SYNCHRONIZED! 
II II 1 1 clause is not specified. I 

II II II Requires floating-point | 
II II 1 I feature. ! 


ICOHP-2 18 (long- | Double- [Fractional | No 1 Same as COHP-1. 1 
1 (internal 1 precision) [word [exponentiation! I I 
1 floating! I | when addition-! [ [ 
1 point) 1 I 1 al precision ! | [ 
1 1 1 1 is required 1 | I 




The following seven cases show how data 
conversions are handled on mixed elementary 
items for names, data comparisions, and 
arithmetic operations, Hoves without the 
CORRESPONDING option to and from group 
items, as well as comparisons involving 
group items, are done without conversion. 



Numeric DISPLAY to COMPUTATION AL-3: 



COMPUTATION AL-3tO COHPDTATIONAL: 



To Move Data : Moves COMPUTATIONAL-3 data 
to a work area and then converts 
COMPUTATIONAL-3 data to COMPUTATIONAL data. 



To Compare Dat a: Converts COMPUTATIONAL 
data to COMPUTATIONAL-3 or vice versa, 
depending on the size of the field. 



To Move Data : Converts DISPLAY data to 
COMPUTATIONAL-3 data. 

To Compare Data : Converts DISPLAY data to 
COHPUTATIONAL-3 data. 



To Perform Arithmetic Operation s: Converts 
COHPUTATIONAL data to COMPUTATIONAL-3 or 
vice versa, depending on the size of the 
field. 



To Perform Arithmetic Operations ; Converts 
DISPLAY data to COMPUTATIONAL-3 data. 



Numeric DISPLAY to COMPUTATIONAL : 

To Hove Data : Converts DISPLAY data to 
COMPUTATIONAL-3 data and then to 
COHPUTATIONAL data. 

To Compare Data ; Converts DISPLAY to 
COMPUTATIONAL or converts both DISPLAY and 
COMPUTATIONAL data to COHPUTATIONAL-3 data. 

To Perform Arithmetic Operations : Converts 
DISPLAY data to COHPnTATIONAL-3 or 
COMPUTATIONAL data. 



COMPUTATIONAL to COHPUTATIONAL- 3: 

To Move Data : Converts COMPUTATIONAL data 
to COMPnTATIONAL-3 data in a work area, and 
then moves the work area. 

To Compare Data : Converts COMPUTATIONAL to 
COMPUTATIONAL-3 data or vice versa, 
depending on the size of the field. 

To Perform Arithmetic Operation s: Converts 
COMPUTATIONAL to COHPUTATIONAL-3 data or 
vice versa, depending on the size of the 
field. 
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COHPOTATIONftL to Numeric DISPLAY : 

To Move Data : Converts COHPUTATIONAL data 
to COMPUTATIONAL-3 data an'd then to DISPLAY 
data. 

To Compare Data : Converts DISPLAY to 
COMPUTATIONAL or both COMPUTATIONAL and 
DISPLAY data to COMPUTATIONAL-3 data, 
depending on the size of the field. 

To Perform Arithmetic Operations : 
Depending on the size of the field, 
converts DISPLAY data to COMPUTATIONAL 
data, or both DISPLAY and COMPUTATIONAL 
data to COHPUTATIONAL-3 data in which case 
the result is generated in a 
COMPUTATIONAL-3 work area and then 
converted and moved to the DISPLAY result 
field. 



The SYNCHRONIZED clause may be used at 
the elementary level to specify the 
automatic alignment of elementary items on 
their proper boundaries, or at the 01 level 
to synchronize all elementary items within 
the group. For COMPUTATIONAL items, if the 
PICTURE is in the range of S9 through 
S9 (4) , the item is aligned on a half word 
boundary. If the PICTURE is in the range 
of S9 (5) through S9 (18) , the item is 
aligned on a fullword boundary. For 
COHPUTATIONAL-1 items, the item is aligned 
on a fullword boundary. For 
COMPUTATIONAL-2 items, the item is aligned 
on a doubleword boundary. The SYNCHRONIZED 
clause and slack bytes are fully discussed 
in the publication IBM System/360 Disk 
Operating System: Full American National 
Standard COBOL. 



COHPUTATIONAL-3 to Numeric DISPLA Y: 

To Move Data : Converts COMPUTATIONAL-3 
data to DISPLAY data. 

To Compare Data : Converts DISPLAY data to 
COMPUTATIONAL-3 data. The result is 
generated in a COMPUTATIONAL-3 work area 
and is then converted and moved to the 
DISPLAY result field. 

Numeric DISPLAY to Numeric DISPLAY : 

To Perform Arithmetic Operations : Converts 
all DISPLAY data to COMPUTATIONAL-3 data. 
The result is generated in a 
COMPUTATIONAL-3 work area and is then 
converted to DISPLAY and moved to the 
DISPLAY result field. 

Internal Floating-point to Any Other : When 
an item described as COMPUTATIONAL-1 or 
COMPUTATIONAL-2 (internal floating-point) 
is used in an operation with another data 
format, the item in the other data format 
is always converted to internal floating- 
point. If necessary, the internal 
floating-point result is then converted to 
the format of the other data item. 



SYNCHRONIZED Clause 



As illustrated in Table 31, 
COMPUTATIONAL, COMPUTATIONAL-1 and 
COMPUTATIONAL-2 items have specific 
boundary alignment requirements. To ensure 
correct alignment, either the programmer or 
the compiler may have to insert slack bytes 
or the compiler must generate extra 
instructions to move the item to a 
correctly aligned work area when reference 
is made to the item. 



Special Considerations for DISPLAY and 
COMPUTATIONAL Fields 



NUMERIC DISPLAY FIELDS 



inserted 

instruct 

is moved 

instruct 

zeros in 

numeric 

field is 

compiler 

smaller 

inserted 



into numeric 
ion set. When 
, the compiler 
ions that inse 
to the DISPLAY 
DISPLAY data i 
smaller than 
generates ins 
item to a work 



Zeros are not 
DISPLAY fields by the 

numeric DISPLAY data 

generates 
rt any necessary 

fields. When 
s compared, and one 
the other, the 
tructions to move the 

area where zeros are 



COMPUTATIONAL FIELDS : COMPUTATIONAL fields 
can be aligned on either a halfword or 
fullword boundary. If an operation 
involves COMPUTATIONAL fields of different 
lengths, the halfword field is 
automatically expanded to a fullword field. 
Therefore, mixed halfword and fullword 
fields require no additional operations. 

COMPUTATIONAL-1 AND COMPUTATIONAL-2 FIELDS ; 
If an arithmetic operation involves a 
mixture of short-precision and 
long-precision fields, the compiler 
generates instructions to expand the 
short-precision field to a long -precision 
field before the operation is executed. 

COMPUTATIONAL-3 FIELDS : The compiler does 
not have to generate instructions to insert 
high-order zeros for ADD and SUBTRACT 
statements that involve COMPUTATIONAL-3 
data. The zeros are inserted by the 
instruction set. 



Data Formats in the Compute r 



The following examples illustrate how 
the various COBOL data formats appear in 
the computer in EBCDIC (Extended 
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Binary-Coded-Decimal Interchange Code) 
format. More detailed information about 
these data formats appear in the 
publication IBH System/370 Principles of 
Operation . 

Numeric DISPLAY (External Decimal) : 
Suppose the value of an item is -1234, and 
its PICTURE and USAGE clauses are: 

PICTURE 9999 DISPLAY. 



or 



PICTURE S9999 DISPLAY. 

The item appears in the computer in the 
following forms, respectively: 



Note that a leading zero is inserted in the 
above example. 



COMPUTATIONAL (Binary) : Suppose the value 
of an item is 1234, and its PICTURE and 
USAGE clauses are: 

PICTURE S9999 COMPUTATIONAL. 

The item appears internally in the 
following form: 

I 0000 I 0100 I 1101 I 0010 I 
I I I I I 

A 



^^m 



I F1 I F2 I F3 I F4 I 



Sign 
Position 



Byte 

I F1 I F2 I F3 I D4 I 
I I I I I 

Byte 

Hexadecimal F is treated arithmetically as 
positive; hexadecimal D represents a minus 
sign. 

COHPUTATIONAL-3 (Internal Decimal) : 
Suppose the value of an item is +1234, and 
its PICTURE and USAGE clauses are: 

PICTURE 9999 COMPUTATIONAL-3. 

or 

PICTURE S9999 COMPUTATIONAL-3. 

The item appears internally in the 
following forms, respectively: 

I 01 I 23 I 4F I 
I i I I 

Byte 
I 01 I 23 I 4C I 



Byte 

Hexadecimal F is treated arithmetically as 
positive; hexadecimal C represents a plus 
sign. 



Note : Since the low^-order byte of an 
internal decimal number always contains a 
sign field, an item with an odd number of 
digits can be stored more efficiently than 
an item with an even number of digits. 



A in the sign position indicates that 
the number is positive. Negative numbers 
are represented in two's complement form; 
thus, the sign position of a negative 
number will always contain a 1. 



For example 
follows: 



1234 would appear as 



I 1111 I 1011 I 0010 I 1110 I 



t 



Sign 
Position 

Binary Item Manipulation : A binary item is 
allocated storage ranging from one halfword 
to two fullwords, depending on the number 
of 9»s in its PICTURE. Table 32 is an 
illustration of how the compiler allocates 
this storage. Note that it is possible for 
a value larger than that implied by the 
PICTURE clause to be stored in the item. 
For example, PICTURE S9 (4) implies a 
maximum value of 9,999, although it could 
actually hold the number 32,767. 



Because most binary items are 
manipulated according to their allotted 
storage capacity, the programmer can ignore 
this situation. For the following reasons, 
however, he must be careful of his data: 



When the ON SIZE ERROR option is used, 
the size test is made on the basis of 
the maximum value allowed by the 
picture of the result field. If a 
size error condition exists, the value 
of the result field is not altered and 
control is given to the imperative- 
statements specified by the error 
option . 
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Table 32. Relationship of PICTURE to Storage Allocation 

I T" 



PICTURE 



I 

|S9 through S9 (ti) 

I 

|S9 (5) through S9 (9) 

I 

|S9 (10) through S9 (18) 



Haximum Working Value 



Assigned Storage 



32,767 
9,223,372,036,85*1,775,807 



One halfword 
One fullword 
Two fullwords 



Note: If TRUNC option is used and data is moved to decimal receiving field, then 
maximum working value for S9(10) through 89(18) PICTURE is 2,147,483,647,999,999,99' 



2. When a binary item is displayed or 
exhibited, the value used is a 
function of the number of 9*s 
specified in the PICTURE clause. 

3. When the actual value of a positive 
number is significantly larger than 
its picture value, a value of 1 could 
appear in the sign position of the 
item, causing the item to be treated 
as a negative number in subseguent 
operations. 

Figure 58 illustrates three binary 
manipulations. In each case, the result 
field is an item described as PICTURE S9 
COMPUTATIONAL. One half word of storage has 
been allocated, and no ON SIZE ERROR option 
is involved. Note that if the ON SIZE 
ERROR option had been specified, it would 
have been executed for cases B and C. 



COMPUTATIONAL-1 or COMPUTATIONAL-2 
(Floating-point) : Suppose the value of an 
item is +1234 and that its USAGE is 
COMPnTATIONAL-1, the item appears 
internally in the following form: 



|0|100 001110100 1101 0010 0000 0000 00001 

I I I I 

S 1 7 8 31 

S is the sign position of the number. 

in the sign position indicates that 
the sign is plus. 

1 in the sign position indicates that 
the sign is minus. 



Bits 1 through 7 are the exponent 
(characteristic) of the number. 

Bits 8 through 31 are the fraction 
(mantissa) of the number. 



This form of 
floating point, 
short -precision 
(COMPUTATIONAL- 
(COMPUTATIONAL- 
56 bits. (For 
floating-point 
publication IBH 
Operation .) 



data is referred to as 
The example illustrates 

floating-point data 
1) . In long-precision 
2) , the fraction length is 
a detailed explanation of 
representation, see the 

SYstem/370 Principles of 



PROCEDURE DIVISION 



The Procedure Division of a program can 
often be made more efficient or easier to 
debug by using some of the techniques 
described below. 



MODULARIZING THE PROCEDURE DIVISION 



Modularization involves organizing the 
Procedure Division into at least three 
functional levels: a main-line routine, 
processing subroutines, and input/output 
subroutines. When the Procedure Division 
is modularized, programs are easier to 
maintain and document. In addition, 
modularization makes it simple to break 
down a program using the segmentation 
feature, resulting in a more efficient 
segmented program. Virtual storage 
implications should be taken into 



r 1 — ■- - - - 1 ■— 1 — - -- — ' — 1 — ■'— 1 

1 1 Hexadecimal Result of j Decimal j Actual Decimal Value | DISPLAY or | 
1 Case 1 Binary Calculation | Equivalent | in Half word of Storage | EXHIBIT Value | 


! ft ! 0008 1 8 ! +8 | 8 | 


1 B ! OOOA 1 10 1 +10 ! 1 


I C 1 C350 i 50000 1 -15536 | 6 | 

II II It 



Figure 58. Treatment of Varying Values in a Data Item of PICTURE S9 
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consideration when rearranging the 
Procedure Division. The COUNT option is 
useful in determining a rearrangement 
scheme - 



OVERALL CONSIDERATIONS 



OPTIMIZE Option 



Main-Line Routine 



The main-line routine should be short 
and simple, and should contain all the 
major logical decisions of the program. 
This routine controls the order in which 
second-level subroutines are executed. All 
second-level subroutines should be invoked 
from the main-line routine by PERFORM 
statements. 



If the OPTIMIZE option is in effect, the 
number of procedure blocks in a program 
cannot exceed 255. A procedure block is 
equivalent to approximately 4096 bytes of 
Procedure Division code. 

If the COUNT option is in effect, the 
number of verb blocks in a program cannot 
exceed 32,767. A verb block consists of a 
set of verbs in which any verb (excluding 
ABEND) in the block is executed if and only 
if all verbs in the block are executed. 
The average program Procedure Division 
contains approximately three verbs per verb 
block. 



■ 



Processing Subroutines 



Processing subroutines should be broken 
down into as many functional levels as 
necessary, depending on the complexity of 
the program. These must be completely 
closed subroutines, with one entry point 
and one exit point. The entry point should 
be the first statement of the subroutine. 
The exit point should be the EXIT 
statement. Processing subroutines can 
PERFORM only lower level subroutines; 
return to the higher level subroutine 
(processing subroutine) must be 
accomplished by a GO TO statement that 
references the EXIT statement. 



INTERMEDIATE RESULTS 



The compiler treats arithmetic 
statements as a succession of operations 
and sets up intermediate result fields to 
contain the results of these operations. 
Examples of such statements are the 
arithmetic statements and statements 
containing arithmetic expressions. See the 
appendix "Intermediate Results" in the 
publication IBM DOS Full American National 
Standard COBOL for a description of the 
algorithms used by the compiler to 
determine the number of places reserved for 
intermediate result fields. 



Input/Output Subroutines 



The input/output subroutines should be 
the lowest level subroutines, since all 
higher level subroutines have access to 
them. There should be one OPEN subroutine 
and one CLOSE subroutine for the program, 
and only one functional (READ or WRITE) 
subroutine for each file. Having one READ 
or WRITE subroutine per file has several 
advantages: 

1. Coding can be added to count records 
on a file, transform blanks into 
zeros, check for 9's padding, etc. 

2. Input and output files can be 
reformatted without changing the logic 
of the program. 

3. DEBUG statements can be added during 
testing to create input or to DISPLAY 
formatted output, instead of having to 
create a test file. 



Intermediate Results and Binary Data Items 



If an operation involving binary 
operands requires an intermediate result 
greater than 18 digits, the compiler 
converts the operands to internal decimal 
before performing the operation. If the 
result field is binary, the result will be 
converted from internal decimal to binary. 

If an intermediate result will not be 
greater than nine digits, the operation is 
performed most efficiently on binary data 
fields. 



Intermediate Results and COBOL Library 
Subroutines 



If a decimal multiplication operation 
requires an intermediate result greater 
than 30 digits, a COBOL library subroutine 
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is used to perform the multiplication. The 
result of this multiplication is then 
truncated to 30 digits. 

A COBOL library subroutine is used to 
perform division if: 

I 1. The divisor (scaled or not) is equal 
I to or greater than 15 digits. 

2. The length of the divisor (scaled or 
not) plus the length of the scaled 
dividend is greater than 16 bytes. 
The lengths of the operands are in 
decimal internally. 

3. The scaled dividend is greater than 30 
digits-. (A scaled dividend is a 
number that has been multiplied by a 
power of ten in order to obtain the 
desired number of decimal places in 
the quotient- ) 



Intermediate Results Greater Than 30 Digits 



Whenever the number of digits in a 
decimal intermediate result is greater than 
30, the field is truncated to 30 digits. A 
warning message will be generated during 
compilation, and program flow will not be 
interrupted at execution time. This 
truncation may cause a result to be 
incorrect. 



If binary or internal decimal data is in 
agreement with its data description, no 
interrupt can occur because of an overflow 
condition in an intermediate result. This 
is due to the truncation described in the 
preceding paragraph. 



If the possibility exists that an 
intermediate result field may exceed 30 
digits, truncation can be avoided by the 
specification of floating-point operands 
(COMPUTATIONAL-1 Or COMPUTATIONAL-2) ; 
however, accuracy may not be maintained. 



Intermedia t e Results and the ON SIZE ERROR 
Option 

The ON SIZE ERROR Option applies only to 
the final calculated results and not to 
intermediate result fields. 



EXPONENTIATION 

When the exponent is not a literal, one 
of the following three subroutines is 
invoked, depending on the base and the 
exponent : 

1. If the base is not a floating-point 
item and the exponent is an integer 
item, a call to the subroutine 
ILBDXPRO is generated and the 
exponentiation is executed in packed 
decimal arithmetic. 

2. If the base is a floating-point item 
and the exponent is an integer item, a 
call to the subroutine ILBDGPWO is 
generated and the exponentiation is 
executed in floating-point arithmetic. 

3. If the exponent is a floating-point 
item or has a PICTURE specifying 
decimal places, a call to the 
subroutine ILEDFPWO is generated and 
the exponentiation is executed in 
floating-point arithmetic. The base 
is always treated as a positive 
number, regardless of sign and the 
answer will always be a positive 
number. Caution should therefore 

be exercised when using non-integer 
exponents . 

When the exponent is an integer literal, 
one of the following applies: 

1. If the base is a floating-point item., 
a call to the subroutine ILBDGPWO is 
generated and the exponentiation is 
executed in floating-point arithmetic. 

2. If the base is not a floating-point 
item, an in-line loop is generated to 
perform the exponentiation unless the 
maximum possible result exceeds 30 
digits, in which case a call to the 
subroutine ILBDXPRO is generated. In 
either case, the exponentiation is 
executed in packed decimal arithmetic. 



Intermediate Results and Floating-point 
Data Items 



Optimization Eased on Execution Frequency 



If a floating-point operand has an 
intermediate result field in which exponent 
overflow occurs, the job will be abnormally 
terminated. 



Additional optimization techniques may 
be us^d based on execution frequency 
statistics. These techniques are discussed 
in the chapter entitled "Execution 
Statistics". 
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PROCEDURE DIVISION STATEMENTS 



COMPUTE Stateme nt 

The use of the COMPUTE statement 
generates more efficient code than does the 
use of individual arithmetic statements, 
since the compiler can keep track of 
internal work areas and does not have to 
store the results of intermediate 
calculations. It is the programmer's 
responsibility, however, to ensure that the 
data is defined with the level of 
significance required in the answer. 
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IF Statement 



Nested and compound IF statements should 
be avoided as the logic is difficult to 
debug. 



HOVE Statement 



Performing a move operation for an item 
longer than 256 bytes requires the 

required for a move operation for an item 
of 256 bytes or less. 

For fields longer than 512 bytes, a MOVE 
LONG (MVCL) instruction is generated unless 
the first byte of the receiving field is 
used as a byte of the sending field. In 
this case, the object-time subroutine 
ILBDVMOO is called to perform the move. 

When a MOVE statement with the 
CORRESPONDING option is executed, data 
items are considered as "corresponding" 
only if their respective data-names are the 
same, including all implied qualification 
up to, but not including, the data-names 
used in the MOVE statement itself. 



For example: 

01 AA 

05 BB 
10 CC 
10 DD 

05 EE 
10 FF 



01 



XX 

05 BB 
10 CC 
10 DD 

05 YY 
10 FF 



whole paragraph to be treated as part of 
the NOTE. Programmer errors can be avoided 
by using the asterisk (*) in place of the 
NOTE statement. 



PERFORM Statement 



PERFORM is a useful statement if the 
programmer adheres to the following rules: 



I irave 



ovisr-n+o + >» o 1ac+ c+ »•♦• o.rao,r>+ r»-f 



series of routines being operated on 
by a PERFORM statement. When 
branching out of the routine, make 
sure control will eventually return to 
the last statement of the routine, 
which should be an EXIT statement. 
Although no code is generated, the 
EXIT statement allows a programmer to 
immediately recognize the extent of a 
series of routines within the range of 
a PERFORM statement. 

Always either PERFORM routine-name 
THRU routine-name-exit, or PERFORM 
section-name. A PERFORM 
paragraph-name can create problems for 
the programmer trying to maintain the 
program. For example, if one 
paragraph must be broken into two 
paragraphs, the programmer must 
examine every statement to determine 
whether this paragraph is within the 
range of the PERFORM statement. As a 
result, all statements referencing the 
paragraph-name must be changed to 
PERFORM THRU statements. 




The statement HOVE CORRESPONDING AA TO XX 
will result in moving CC, and DD, but not 
FF, since FF of EE does not correspond to 
FF of YY. 

The compiler assumes that the data being 
moved conforms to PICTURE and USAGE 
specifications. If it does not, dissimilar 
results will occasionally occur because of 
the different code generated for various 
sending and receiving fields. This fact is 
most apparent when the sending field is 
COMPUTATIONAL, the value in the item 
exceeds the number of digits specified in 
the PICTURE clause, and the option NOTRUNC 
is in effect. 



Note; 



The other rules for MOVE 



CORRESPONDING, of course, must still be 
satisfied. 



NOTE Statement 



When the NOTE statement is the first 
statement in a paragraph, it will cause the 



A PERFORM statement containing 
embedded PERFORMS or PERFORM VARYING 
with one or more AFTER options causes 
the compiler to generate complex code. 
If a series of simple PERFORM 
statements can accomplish the same 
function, the programmer would be wise 
to substitute these since more 
efficient code is generated. 



HEAD INTO AND WRITE FROH OPTIOHS 



Always use READ INTO and WRITE FROM, and 
process all files in the Working-Storage 
Section for the following reasons: 

1. Debugging is much simpler. 

Working-Storage areas are easier to 
locate in a dump than are buffer 
areas. And, if files are blocked, it 
is much easier to determine which 
record in a block was being processed 
when the abnormal termination 
occurred. 
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2. Trying to access a record-area after TRANSFOR!! Statement 
the AT END condition has occurred (for 
example, AT END HOVE HIGH-VALUE TO 

INPUT-RECORD) can cause problems if The TRANSFORM statement generates more 
the record area is defined only in the efficient code than the EXAMINE REPLACING 
File Section. BY statement when only one character is 

being transformed. The TEANSFORH 

Note : The programmer should be aware that statement, however, uses a 256-byte table. 

additional time is used to execute the move 

operation involved in each READ INTO or 

WRITE FROM instruction. 



206 



USING THE SORT/MERGE FEATURE 



To use the Sort Feature, statements are 
written in the COBOL source program. These 
statements are described in IBM DOS Full 
American National Standard COBOL . The 
Sort/Merge publications listed in the 
Preface of this manual contain information 
on the Sort/Merge feature. 

When a SORT or MERGE statement is used 
in a program, the compiler generates 
linkages between the program, modules in 
the subroutine library, and the Sort/Merge 
program. The name of Sort/Merge called by 
COBOL is "SORT" and the user must include 
the proper one on the option. 

Depending on the features specified and 
devices to be used by Sort/Merge, different 
Sort/Merge products should be used: 



SORT INPUT AND OUTPUT CONTROL STATEMENTS 



When the USING and/or GIVING options are 
specified, the compiler generates dummy 
Input and/or Output Procedures. Hence, the 
job control requirements for files named as 
operands of USING and GIVING are the same 
as those for files used as input to or 
output from the sorting operation in these 
procedures. 

The following job control statements are 
required for files used as input to or 
output from the sorting operation: 

ASSGN 






followed by 



Feature 
VSAM 
MERGE 

ASCII-Collated Sort 
Niameric Sort keys with 
Sign in the form of 
leading overpunch or 
separate character. 
3330/3333 Sort Work 

files 
3330-11 Sort Work 

files 
3340 Sort Work files 
3350 Sort Work files 
3400 Sort Work files 
2311 Sort Work files 



Product 
Requirement 
5746-SMl 
5746-SMl 

5743-SMl, 5746-SMl 
5743-SMl, 5746-SMl 



5743-SMl, 5746-SMl 

5746-SMl 

5746-SMl 
5746-SMl 

5743-SMl, 5746-SMl 
SM-483, 5743-SMl 

The program product DOS/VS Sort/Merge, 
5746-SMl, is designed specifically for use 
with DOS/VS. 

Otherwise, IBM DOS Tape and Disk 
Sort/Merge, 360N-SM-483, can be used. 

Additional job control statements must 
be included in the execution step of the 
job to describe the files used by the sort 
program. These statements are described 
below in "Sort Job Control Requirements." 

Note : The Checkpoint/Restart Feature can 
be activated during a sorting operation by 
specifying the RERUN statement. 

SORT/MERGE JOB CONTROL REQUIREMENTS 

Three types of files can be defined for 
the Sort program in the execution job step: 
input, output, and work. Two types of 
files can be defined for the Merge program 
in the execution job step: input and 
output . 



or 



or 



VOL 
TPLAB 



VOL 

DLAB 

XTENT 



DLBL 
EXTENT 



or 



TLBL 

The symbolic unit to which each sort 
input or output file is assigned in the 
source language ASSIGN clause is specified 
in an ASSGN control statement. 

Note: ASSGN control statements are 
required only if the input/output devices 
used in an application have not been 
previously assigned the appropriate 
symbolic names. 

If an input file contains standard 
labels, a TLBL or DLBL (or VOL and TPLAB or 
VOL and DLAB) statement (s) is required. 
The symbolic name of the device from which 
the input file is to be read must also be 
included on this statement. 

One EXTENT control statement is required 
to define the limits of each area of a mass 
storage device from which an input file 
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will be read. EXTENT statements must 
include the symbolic unit name of the 
device containing the extent. 

If the output file is to use standard 
labels, a TLBL or DLBL statement is 
required. 

One EXTENT control statement must be 
used to define the limits of each area of a 
mass storage device onto which the output 
file is written. The symbolic name of the 
output unit must appear on this card. 

Note : Because the USING and GIVIl^KS options 
generate dummy input and/or Output 
procedures, the rules on pooling of files 
in the Sort/Merge Programmer's Guide 
referenced above do not apply. No pooling 
of Sort input, output, and work files is 
allowed. 

A SIZE parameter is needed in the EXEC 
statement- when sorting a VSAM file. The 
SIZE parameter must be in the format 
SIZE=(AUTO,nK) to take into account the 
fetching of the sort module during execu- 
tion and VSAM storage requirements. 

SORT WORK FILE CONTROL STATEMENTS 

The Sort program requires at least one 
mass storage unit or three tape units as an 
intermediate sort work file. The symbolic 
units to which this file is assigned are 
normally consecutively numbered beginning 
with SYSOOl. Intermediate storage may be 
assigned on the following devices: 

• IBM 2400 Series Magnetic Tape Units 

• IBM 3400 Series Magnetic Tape Units ^ 

• IBM 2311 Direct-Access Storage Device 

• IBM 2314/2319 Direct-Access Storage 
Facility 

• IBM 3330/3333 Direct-Access Storage 
Facility' 

• IBM 3330-11 Disk Storage' 

• IBM 3340 Direct-Access Storage 
Facility' 

• IBM 3350 Direct Access Storage' 

Note : When variable-length or 
redefined-length records are being sorted, 
sort work files must not be assigned to 
7-track tapes. 7-track tape work files can 
only be used to sort records whose keys are 
packed decimal or binary. 

Device types may not be mixed; i.e., 
work units for a particular sort operation 
must all be of the same typ*^ 

^Only supported by the DOS Sort/Merge 
Program Product, Program Number 5743-SMl 
or the DOS/VS Sort/Merge Program Product, 
Program Number 5746-SMl (see above). 



If spanned records are being sorted and 
mass storage devices are being used as sort 
work files, it is the programmer's 
responsibility to assign these work files 
to devices whose track sizes are larger 
than the logical record sizes of the 
records being sorted. -^A spanned record 
that is larger than the available track 
size can be sorted by assigning the work 
files to magnetic tape. 

If a work unit is to use standard 
labels, a TLBL or DLBL control statement is 
required. The filename entry on these 
statements must be SORTWKl through SORTWKn. 
The symbolic unit names assigned to the 
work areas to be allocated (SYSOOl, SYS002, 
etc.) must appear on these cards. 

One EXTENT control statement must be 
included to define each work area on a mass 
storage device. The total work area 
required may be divided into as many as 
eight extents, which would require eight 
EXTENT control statements. When code SD is 
specified on the DLBL card, symbolic unit 
names on these statements must be in 
consecutive order (SYSOOl, SYS002, etc.). 
If SORT-OPTION is specified, the symbolic 
unit names must be in the same order as 
specified on SORTWK. 

If SYSLST is assigned to a disk, the 
option PRINT=NONE or ROUTE=LOG must 
be used. 

Amount of Intermediate Storage Required 

When intermediate storage is assigned on 
a mass storage unit, at least twice the 
amount required to hold all input records 
should be assigned. This area may consist 
of from one to eight extents, and the 
extents may be assigned on no more than 
eight devices- 

If tape intermediate storage is used, at 
least the minimum number of units (three) 
must be assigned. The input file can be as 
large as the number of records that can be 
written on one full reel of tape. 
Assigning more than three intermediate 
storage tape drives does not increase the 
maximum input file size, but does improve 
performance. 



Improving Performance 



Performance increases significantly if 
50K of real storage is available for 
execution of the Sort program. At the 10 OK 
level, the performance is very high. If 
insufficient virtual storage is available, 
the Sort/Merge program will issue a 
message: 



7054A 



'INSUFFICIENT CORE" 
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SORT-OPTION Claus« 



The "SORT-OPTION" clause is a means of 
specifying the options that have been 
selected for the associated sort/merge 
operation that cannot be specified via the 
SORT special registers- The format of the 
contents of the data-name is shown in 
Figure 58.1. This corresponds to the 
SORT/MERGE option statement. No validity 
check is done by COBOL; only the address 
is passed to SORT/MERGE. For more details 
on specific options for SORT, see IBM 
DOS/VS Sort/Merge Programmer's Guide . 

Note : The COBOL-SORT interface does not 
allow any preceding blanks in front of the 
"SORT-OPTION" clause. One and only one 
blank must follow the keyword OPTION. At 
least one blank must follow the last 
operand. 



OPTION 

'PRINT 

PRINT=NONE 

PRINT=ALL 
.PRINT=CRITICAL_ 

t,LABEL=(,,WORK)] 

'n 
InK 



, STOR AGE= ) ( n , V IRT ) 
(nK,VIRT) 

[,ALTWK] [, ERASE] 



- ROUTE=LST 
., ROUTE=LOG_ 



", SORTWK=WOrk 
_,SORTWK=(worki, work) 

L . J 

Figure 58. 1« OPTION Control Statement to 
SORT/MERGE 



PRINT Option 



PRINT 
PRINT=NONE 
PRINT=ALL 
PRINT=CRITICAL 



PRINT and PRINT=ALL specify that all 
messages are to be printed by the 
sort/merge program. This includes error 
and end-of-job messages, control card 
information, various size calculations, and 
other informative messages. 

PRINT=NONE specifies that no messages 
are to be printed by the sort/merge 
program- This parameter is useful if you 
have no alternate message device and do not 



want messages listed with other printed 
output. A message device need not be 
assigned. 

PRINT=CRITICAL specifies that only 
messages critical to the sort/merge 
program's operation are to be printed. 
These are error messages resulting from 
conditions that can cause program 
termination. For more details en these 
conditions and messages, refer to IBM 
DOS/VS Sort/Merge Programmer ' s Guide . 



Note: PRINT=ALL is assiomed until the 
OPTION statement is read, therefore, if 
PRINT=NONE or PRINT=CRITICAL will be used, 
the OPTION statement should precede all 
others- 



LABEL Option 



[LAEEL=(,,work)] 

This operand specifies the type of 
labels associated with the work files. The 
two label types are: 

S - standard labels 
U - unlabeled 

The default is S, standard labels. 

Work must be replaced by S or U. This 
operand is required if the OPTION statement 
is specified, and unlabeled work files are 
used. If the operand is om.itted, standard 
labels are assumed for all files. 

When standard labels are used, the 
sort/merge program uses the DOS/VS system 
facilities to process these labels. 
Unlabeled tape files are processed by the 
sort/merge program. No user programming is 
required. 



STORAGE Option 



) 

inK f 

,STORAGE='i(n,VIRT) f 
(nK,VIRT))_ 



This option is required to specify to 
the sort/merge program how much storage to 
use and whether it can fix pages. 



^M 



STORAGE=n 
_STORAGE={n,VIRT 



>] 



n specifies the amount of storage to be 
made available to sort/merge (together witl 
its user routines), n can be specified 
either as a decimal numbei of bytes, or as 
a decimal number of K (1024 bytes). 
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The dsfault is the vslue of the SXZE 
parameter on the EXEC job control 
statement. If both SIZE and STORAGE are 
specified, the lower value is taken. If 
neither is specified, the default is the 
partition size or the required size 
calculated by sort/merge (but at least 
64K) , whichever is smaller. The sort/merge 
program terminates if n is less than 16K 
bytes. If n is greater than the partition 
size, it is ignored. 

If the sort/merge program is invoked 
from another program, the defaults are 
calculated in a similar way, but the value 
of the SIZE parameter and the partition 
size are adjusted downwards by the 
difference between the address of the 
sort/merge load point and the beginning 
address of the partition. 

VIRT 

If VIRT is specified, the sort/merge 
program will not attempt to fix pages when 
running in virtual mode. It may be 
necessary to specify VIRT to prevent 
interference with other jobs running 
simultaneously, or to allow a user-written 
routine to fix pages. VIRT should be 
avoided wherever possible since it has an 
unfavorable effect on sort/merge 
performance. VIRT is ignored when the 
sort/merge program is running in real mode. 
The value in SORT-CORE-SISE will be ignored 
if the OPTION clause is specified. 



ALTWK Option 



ALTWK specifies an alternate work drive 
(tape only) in a sorting job. This doubles 
the maximum input file size allowed. The 
address of the alternate device must be 
different from the address of all other 
devices used in the job. 



Note that the sen 

work data sets, even when terminating 

normally. 



ROUTE Option 



r,ROUTE=LSTl 

L,route=logJ 

,ROUTE=LST specifies that messages are 
to be routed to the SYSLST file by the 
sort/merge program. Messages requiring 
operator intervention will also be printed 
on SYSLOG if allocated to a DOS/VS 
supported console device. 

,ROUTE=LOG specified that messages are 
to be routed to the console. 



Note; 



The default is assumed until the 



OPTION card has been read. 



SORTWK Option 



,SORTWK=work 

, SORTWK= ( worki , work ) 



This operand specifies the logical unit 
numbers associated with the work files. 
The parameters within parentheses must be 
replaced by symbolic unit numbers of a 
maximum of three significant digits from 1 
to 221, or by a comma. When a comma is 
coded, or if the operand is omitted, the 
sort program will use the default 
assignment. 



ERASE Option 



SORT-OPTION Clause Examples 



ERASE specifies that work data sets used 
during a sorting operation are to be erased 
at the end of the job. It is ignored if 
2400-series tapes are used for work areas. 
If the sort operation terrr" nates 
abnormally, 

• ERASE will be performed unless the 
checkpoint facility has been specified; 

• if ERASE is performed, and if a 
workfile has been pooled with output, 
the output file will also be erased. 



SORT-OPTION is SRTOPTN where SRTOPTN is 
defined in working-storage section. At 
entry to SORT/MERGE, the contents of 
SRTOPTN is as follows. 

Example 1 : 

OPTION PRINT=ALL,STORAGE=26 38U,LAEEL=(,,U) 

All messages are requested, the virtual 
storage available to the sort/merge program 
is 26,384 bytes, and the work volume is 
unlabeled. 
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Example 2 : 



OUTPUT FILE STATEMENTS 



OPTION STORAGE=32K, ERASE, ROUTE=LST, 
SORTWK=(005,006) 

The PRINT option is not specified, so 
all messages will be printed by default. 
The storage available to the sort/merge 
program is 32K bytes. Standard labels, by 
default, are assumed for all files. The 
data sets used by sort are to be erased on 
completion of the sort operation. All 
messages are to be routed to the printer. 
The logical numbers of the work files are 
SYS005 and SYS006, 

Example 3 ; 

OPTION SORTWK=(0 10, 11, 12, , 14,15) , ALTWK 

1. Assume work=3 (specified on the SELECT 
statement associated with the SD 
file); then, using M from Figure 58.2 
(M=3) since, in this example, no 
overide for the alternate work unit is 
specified, allocate as follows: 

SYSOIO, SYSOll and SYS012 are the 
logical unit numbers of the work 
files. SYS004 is the logical unit for 
the alternate work device by default. 
SYS (M+1) =SYS ( 3+1) =SYS004. 

SYS014 and SYS015 are not used in 
this application since W0RK=3. 

This example shows how the values 
interact. The example may be 
understood as showing a sort operation 
which was set up to run with five work 
files, but which for this particular 
run, has only three work files. (Note 
the assiimption that work=3.) 

2. Assume W0RK=5, then 

SYSOIO, SYSOll, SYS012, SYS004, and 
SYS 014 are the logical unit numbers of 
the work files. SYS015 is the logical 
unit for the alternate device. 

Example 4 ; 

A convenient way to specify the OPTION 
card at execution time is to use the card 
as a data card on SYSIPT and in the program 
specify 

SORT-OPTION IS EXEC-SORT 



The TLBL or DLBL statement file-name 
must be SORTOUT. Multivolume and/or 
multiextent output on disk is accomplished 
by using DOS/VS standards: one DLBL card 
is supplied for the entire file followed by 
one EXTENT card for each separate extent 
that the file occupies on the disk pack or 
packs. Where the output file is a 
direct-access multiextent file, only the 
first EXTENT statement need contain the 
specified or defaulted symbolic unit name 
for the output file. Other EXTENT 
statements may specify any valid symbolic 
unit name. Figure 58.2 gives the 
file-names and default symbolic unit names 
in the sort/merge program. 



r T T 1 

jUse of Device I Filename I Symbolic Unit Name] 
j. ^ 1 ^ 

1 Work jSORTWKl 1 SYS 001 | 
I j . I - 1 

! I . ! . I 

I I . 1 . I 

I IS0RTWK9 I SYS(M) j 
|. 1 + ^ 

] ALTWK ISORTALT | SYS (M+1) j 
j. X J ^ 

|M=the number of work files, as specified | 
1 in the SELECT statement for the SD | 
I file. I 

L J 

Figure 58,2. File Name and Default 
Symbolic Unit Names 



^m 



ACCEPT EXEC- SORT FROM SYSIPT. 
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r T 

i Statement 



Operands 



Coitiments 



OPTION I PRINT= {ALL I NONE) CRITICAL} or PRINT j Default=ALL 

+ 

STORAGE=n| (n,VIRT) I (nK, .) | Default. See discussion. 

+ 

LABEL=(, ,work) I Default=standard labels 
^ 

ALTWK 1 
+ 

ERASE j 
^ 

ROUTE={LST|LOG} | Default PhO msg on printer and 

I console and Phl-3 on console. 
1 

(worki ) I 

SORTWK=^ V 1 Default={l,2,...iii) 

) {workj_, . . . „work )j | 

L ± X 

Figure 5 8.3. SUMMARY OF SORT-OPTION Operands 
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SORT DIAGNOSTIC HESSAGES 



The messages generated by the Sort/Merge 
Feature are listed in the sort publications 
referenced in the preface. 



LINKAGE WITH THE SORT/HEEGE FEATURE 



To initiate a sort or merge operation, 
the COBOL object program includes the 
object time subroutines ILBDSRTO and 
ILBDHRGO and transfers control to them. 

If the INPUT PROCEDURE option of the 
SORT statement is specified in the source 
program, exit E15 of the Sort/Merge program 
is used- At this exit, the record released 
by the programmer is passed to the 
Sort/Herge program. Since a dummy Input 
Procedure will be generated by the compiler 
when the USING option is specified, records 
in the USING file are also passed to the 
Sort/Herge program at exit E15. Records in 
the USING file of a Merge operation are 
passed at exit E32. 

If the OUTPUT PROCEDURE option of the 
SORT statement is specified, exit E35 of 
the Sort/Merge program is used. At this 
exit, the record returned by the Sort/Merge 
program is passed to the programmer. Since 
a dummy Output Procedure is generated by 
the compiler when the GIVING option is 
specified, records are also returned at 
exit E35 and written on this file. Exit 
E32 is used for the output procedure option 
of the HERGE statement. 



16 — Unsuccessful completion of 
Sort/Merge 



Successful Completion : When a Sort/Merge 
application has been successfully executed, 
a completion code of zero is returned and 
the sort operation terminates. 



Unsuccessful Completion : If the Sort 
program encounters an error during 
execution that will not allow it to 
complete successfully, it returns a 
completion code of 16 and terminates. (A 
possible error is an uncorrectable 
input/output error.) The sort publications 
contain a detailed description of the 
conditions under which this termination 
will occur. 



The user may test the SORT-RETURN 
register for successful termination of the 
sort operation, as shown in the following 
example: 



SORT SALES-RECORDS ON ASCENDING KEY, 

CUSTOHER-NUHBER, DESCENDING KEY DATE, 
USING FN-1, GIVING FN-2. 



IF SORT-RETURN NOT EQUAL TO ZERO, DISPLAY 
"SORT UNSUCCESSFUL" UPON CONSOLE, STOP 
RUN. 



Cataloging a Sort Program 



i 



Completion Codes 

The Sort/Merge program returns a 
completion code upon termination and this 
code is stored in the COBOL special 
register SORT-RETURN. The codes are: 

— Successful completion of 
Sort/Merge 

02 — Invalid OPEN — USING file 

04 — Permanent I/O error — USING file 

06 — Invalid OPEN — GIVING file 

08 — Permanent I/O error — GIVING 
file 

10 — Boundary violation — GIVING file 

12 — Duplicate or out of seguence key 
~ GIVING file 



When the CATAL option is used to catalog 
a sort program, the following should be 
observed: 

• To avoid duplicate names when selecting 
a catalog name for his program, the 
programmer must be aware of the naming 
convention used by the compiler to 
generate the name of the dummy phase 
into which the phases of the Sort/Herge 
program will subsequently be loaded. 



Naming Convention : The compiler generates 
the phase card for the dummy phase using 
the following convention: 

• If the PROGRAM-ID name is 6, 7, or 8 
characters in length, the dummy phase 
name consists of the first 6 characters 
plus 2 zero characters. 

• If the PROGRAM-ID name is less than 6 
characters in length, the name is 
padded with zeros to 8 characters. 
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Since the system expects the first 
character of PEOGRAM-ID to be 
alphabetic, the first character, if 
numeric, is converted as follows; 



The RERDN' clause is fully described in 
the publication IBM DOS Pull American 
National Standard COBOL. 



-> J 
1-9 _> A-I 



USING SORT IN A HDLTIPHASE ENVIRONMENT 



The hyphen is converted to zero if it 
appears as the second through eighth 
character. 



CHECKPOINT/RESTART DURING A SORT 



The Checkpoint/Restart Feature is 
available to the programmer using the COBOL 
SORT statement. The programmer uses the 
RERUN clause to specify that checkpoints 
should be taken during program execution. 
The control statement requirements for 
taking a checkpoint are discussed in the 
section entitled "Program Checkout." 
Checkpoint/Restart is not available during 
a merge operation. 

The system-name specified in the RERUN 
clause as the sort checkpoint device must 
not be the same as any system-name used in 
the source language ASSIGN clause, but 
follows the same rules of formation. 



When the Sort program is invoked in a 
multiphase environment, the following 
should be noted: 

1. It is the programmer's responsibility 
to ensure that the COBOL program 
containing the SORT statement is the 
highest phase in storage. 

2. If two programs are compiled, link 
edited, and executed together, only 
one program may use the Sort feature. 
If both programs require Sort, the 
programs can be compiled separately 
and then the decks must be organized 
so that the dummy phase cards for Sort 
are both together at the end of the 
deck before they are link edited and 
executed. 

3. If Debug and Sort are used together, 
the Debug modules must be included 
in the root phase. 



I 
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USING THE REPORT WRITER FEATURE 



REPORT Clause in a File Description (FD) 
Entry 



A given report-name may appear in a 
maximum of two file description entries. 
The file description entries need not have 
the same characteristics, but both must be 
standard sequential. If the same 
report-name is specified in two file 
description entries, the report will be 
written on both files. For example: 



ENVIRONMENT DIVISION. 

SELECT FILE-1 ASSIGN SYS005-UR-1403-S. 
SELECT FILE-2 ASSIGN SYS001-UT-2400-S. 



DATA DIVISION. 

FD FILE-1 RECORDING MODE F 

RECORD CONTAINS 121 CHARACTERS 

REPORT IS REPORT-A. 
FD FILE-2 RECORDING MODE V 

RECORD CONTAINS 101 CHARACTERS 

REPORT IS REPORT-A. 

For each GENERATE statement, the records 
for REPORT-A will be written on FILE-1 and 
FILE-2, respectively. The records on 
FILE-2 will not contain columns 102 through 
121 of the corresponding records on FILE-1. 



Method 1 ; 

01 TYPE CONTROL FOOTING YEAR. 

02 SUM COST, 
01 TYPE CONTROL FOOTING MONTH. 

02 SUM COST. 
01 TYPE CONTROL FOOTING WEEK. 

02 SUM COST- 
01 TYPE CONTROL FOOTING ADAY. 

02 SUM COST. 

Method 2 ; 

01 TYPE CONTROL FOOTING YEAR. 

02 SUM A. 
01 TYPE CONTROL FOOTING MONTH. 

02 A SUM B. 
01 TYPE CONTROL FOOTING WEEK. 

02 B SUM C. 
01 TYPE CONTROL FOOTING ADAY. 

02 C SUM COST. 



Method 2 will execute faster. One 
addition will be performed for each day, 
one more for each week, and one for each 
month. In Method 1, four additions will be 
performed for each day. 



i 



Use of SUM 



Summing Techniques 



Execution time of an object program can 
be decreased by keeping in mind that Report 
Writer source coding is treated as though 
the programmer had written the program in 
COBOL without the Report Writer feature. 
Therefore, a complex source statement or 
series of statements will generally be 
executed faster than simple statements that 
perform the same function. The following 
example shows two coding techniques for the 
Report Section of the Data Division. 
Method 2 uses the more complex statements. 

RD.. .CONTROLS ARE YEAR MONTH WEEK DAY. 



Unless each identifier is the name of a 
SUM counter in a TYPE CONTROL FOOTING 
report group at an equal or lower position 
in the control hierarchy, the identifier 
must be defined in the File, Working- 
Storage, or Linkage Sections as well as in 
a TYPE DETAIL report group as a source item 
or no summing will occur. A SUM counter is 
algebraically incremented just before 
presentation of the TYPE DETAIL report 
group in which the item being summed 
appears as a source item or the item being 
simmed appeared in a SUM clause that 
contained an UPON option for this DETAIL 
report group. This is known as SOURCE-SUM 
correlation. In the following example, 
SUBTOTAL is incremented only when DETAIL- 1 
is generated. 
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FILE SECTION. 



02 NO-PURCHASES PICTURE 99. 



REPORT SECTION. 

01 DETAIL- 1 TYPE DETAIL. 

02 COLUMN 30 PICTURE 99 SOURCE 
NO-PURCHASES. 



sequence in which the DETAIL report groups 
are specified. 

The following two examples show the SUM 
routines that are generated by the Report 
Writer. Example 1 illustrates how operands 
are selected for inclusion in the routine 
on the basis of simple SOURCE-SUM 
correlation. Example 2 illustrates how 
operands are selected when the UPON 
detail-name option is specified. 

Example 1 ; The following statements are 
coded in the Report Section: 



01 DETAIL- 2 TYPE DETAIL. 



01 DETAIL- 1 TYPE DE 
02 SOURCE A. 



01 ADAY TYPE CONTROL FOOTING 
LINE PLUS 2. 



01 DETAIL- 2 TYPE DE 

02 SOURCE B- 

02 SOURCE C- 



02 SUBTOTAL COLUMN 30 PICTURE 999 
SUM NO- PURCHASES. 



01 DETAIL- 3 TYPE DE 
02 ... SOURCE B. 



01 MONTH TYPE CONTROL FOOTING 
LINE PLUS 2 NEXT GROUP 
NEXT PAGE. 



01 TYPE CF . . . 
02 SUM-CTR-1 



,SUM A, E, C. 



SUM Routines 



A SUM routine is generated by the Report 
Writer for each DETAIL report group of the 
report. The operands included for summing 
are determined as follows: 



01 TYPE CF ... 

02 SUM-CTR-2 SUM B. 

A SUM routine is generated for each 
DETAIL report group, as follows: 



1. The SUM operand (s) also appears in a 
SOURCE clause (s) for the DETAIL report 
group. 

2. The UPON detail-name option was 
specified in the SUM clause. In this 
case, all the operands are included in 
the SUM routine for only that DETAIL 
report group, even if the operand 
appears in a SOURCE clause in other 
DETAIL report groups. 

When a GENERATE detail-name statement is 
executed, the SUM routine for that DETAIL 
report group is executed in its logical 
sequence. When GENERATE report-name 
statement is executed and the report 
contains more than one DETAIL report group, 
the SUM routine is executed for each one. 
The SUM routines are executed in the 



SUM-ROUTINE FOR DETAIL-1 

REPORT- SAVE 

ADD A TO SUM-CTR-1. 
RE PORT- RETURN 

SUM- ROUTINE FOR DETAIL- 2 

REPORT- SAVE 

ADD B TO SUM-CTR-1. 

ADD C TO SUM-CTR-1. 

ADD B TO SUM-CTR-2. 
REPORT-RETURN 

SUM-ROUTINE FOR DETAIL- 3 

REPORT- SAVE 

ADD B TO SUM-CTR-1. 
ADD B TO SUM-CTR-2. 

■nTrr>rvprr^TJTprnT-Tr.M 



1 
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Example 2 : This example uses the same 
coding as Example 1, with one exception: 
the UPON detail-name option is used for 
SOM-CTR-1, as follows: 

01 TYPE CF . .. 

02 SDM-CTE-1 ...SDH fi, B, C 
UPON DETAIL-2. 

The following SUM routines would then be 
generated instead of those shown in the 
previous example: 

SUH Routine for DETAIL-1 

REPOBT-SAVE 
REPORT-RETURN 

SUM Routine for DETAIL-2 

REPORT-SAVE 

ADD A TO SUM-CTR-1. 

ADD B TO SDK-CTR-1. 

ADD C TO SUH-CTR-1. 

ADD B TO SDH-CTR-2. 
REPORT-RETURN 

SUH Routine for DETAIL-3 

REPORT-SAVE 

ADD B TO SUH-CTR-2. 
REPORT-RETURN 



Output Line Overlay 



The Report Writer output line is created 
using an internal REDEFINES specification, 
indexed by inteqer-1 . No check is made to 
prevent overlay on any line. For example: 

02 COLUMN 10 PICTURE X (23) 

VALUE "HONTELY SUPPLIES REPORT". 

02 COLUHN 12 PICTURE X (9) 
SOURCE CURRENT-MONTH. 

A length of 27 in column 10, followed by a 
specification for column 12, will cause 
field overlay when this line is printed. 



Page Breaks 



The Report Writer page break routine 
operates independently of the routines that 
are executed after any control breaks 
(except that a page break will occur as the 
result of a LINE NEXT PAGE clause) , Thus, 
the programmer should be aware of the 
following facts: 

1. A Control Heading is not printed after 
a Page Heading except for first 
generation. If the programmer wishes 
to have the equivalent of a Control 



Heading at the top of each page, he 
must include the information and data 
to be printed as part of the Page 
Heading. Since only one Page Heading 
may be specified for each report, he 
should be selective in considering his 
Control Heading because it will be the 
same for each page, and may be printed 
at inappropriate times (see "Control 
Footings and Page Format" in this 
chapter) . 

GROUP INDICATE items are printed after 
page and control breaks. Figure 56 
contains a GROUP INDICATE clause and 
illustrates the execution output. 



REPORT SECTION. 



01 DETAIL-LINE TYPE IS DETAIL LINE 

NUMBER IS PLUS 1. 

02 COLUMN IS 2 GROUP INDICATE 
PICTURE IS A (9) SOURCE IS 
MONTHNAME OF RECORD-AREA (MONTH) 



(Execution Output) 



JANUARY 



15 



AOO.. . 
A02. .. 



PURCHASES AND COST.. 



JANUARY 



21 



A03. 
A03. 



4 



Figure 59. Sample of GROUP INDICATE Clause 
and Resultant Execution Output 



WITH CODE Clause 



When more than one report is being 
written on a file and the reports are to be 
selectively written, a unique 1-character 
code must be given for each report. A 
mnemonic-name is specified in the RD-level 
entry for each report and is associated 
with the code in the Special-Names 
paragraph of the Environment Division. 



Note: If a report is written with the CODE 
option, the report should not be written 
directly on a printer device. 



This code will be written as the first 
character of each record that is written on 
the file. When the programmer wishes to 
write a report from this file, he needs 
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only to read a record, check the first 
character for the desired code, and have it 
printed if the desired code is found. The 
record should be printed starting from the 
third character, as illustrated in Figure 
60. 



01 PRINT-REC. 
05 FILLER 



PROCEDORE DIVISION. 



PICTURE X{121) 



I 1 1 

I I Control I 

I Code I Character {Record 

I I I 



Figure 60. Format of a Report Record When 
the CODE Clause is Specified 



LOOP. READ RPT-IN-FILE AT END 

GO TO CONTINUE. 

IF CODE-CHR = "A" 

WRITE PRINT-REC FROH PRINT-PART 

AFTER POSITIONING CTL-CHR LINES. 

GO TO LOOP. 
CONTINUE. 



The following example shows how to 
create and print a report with a code of A 
A Report Writer program contains the 
following statements: 

ENVIRONMENT DIVISION. 



SPECIAL-NAMES, 



DATA DIVISION, 



REPORT SECTION. 
RD EEP-FILE-A 



RD REP-FILE-B 



"A" IS CODE-CHE-A 
"B" IS CODE-CHR-B. 



CODE CODE-CHR-A 



CODE CODE-CHR-B . 



A second program could then be used to 
print only the report with the code of A, 
as follows: 

DATA DIVISION. 
FD RPT-IN-FILE 

RECORD CONTAINS 122 CHARACTERS 

LABEL RECORDS ARE STANDARD 

DATA RECORD IS RPT-RCD. 
01 RPT-RCD. 

05 CODE-CHR PICTURE X. 

05 PRINT-PART. 

10 CTL-CHR PICTURE X. 
10 RECORD-PART PICTURE X (120) . 
FD PRINT-FILE 

RECORD CONTAINS 121 CHARACTERS 

LABEL RECORDS ARE STANDARD 

DATA RECORD IS PRINT-REC. 



Control Footings and Page Forma t 



Depending on the number and size of 
Control Footings (as well as the page depth 
of the report) , all of the specified 
Control Footings may not be printed on the 
same page if a control break occurs for a 
high-level control. When a page condition 
is detected before all reguired Control 
Footings are printed, the Report Writer 
will print the Page Footing (if specified) , 
skip to the next page, print the Page 
Heading (if specified) and then continue to 
print Control Footings. 



If the programmer wishes all of his 
Control Footings to be printed on the same 
page, he must format his page in the 
RD-level entry for the report (by setting 
the LAST DETAIL integer to a sufficiently 
low line number) to allow for the necessary 
space . 



NEXT GROUP Clause 



Each time a CONTROL FOOTING report group 
with a NEXT GROUP clause is printed, the 
clause is activated only if the report 
group is associated with the control that 
causes the break. This is illustrated in 
Figure 61. 
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FD EXPENSE-REPORT CONTROLS ARE FINAL, 
MONTH, ADAY 



01 TYPE CONTROL FOOTING DAY 
LINE PLDS 1 NEXT GROUP 
NEXT PAGE. 



± J. c ij \^\ja IKOlt 



FOOTING MONTH 



LINE PLDS 1 NEXT GROUP 
NEXT PAGE. 



(Execution Output) 
EXPENSE REPORT 



January 31 29.30 

(Output for CF ADAY) 

January total. .. ..131.40 
(Output for CF MONTH) 



Figure 61. Activating the NEXT GROUP 
Clause 

Note : The NEXT GROUP NEXT PAGE clause for 
the Control Footing DAY is not activated. 



relative line as its first line will have 
its relative line -is^pacing suppressed; the 
first line will be printed on either the 
value of FIRST DETAIL or INTEGER PLUS 1 of 
a NEXT GROUP clause from the preceding 
page. For example: 

1. If the following body group was the 
last to be printed on a page 

01 TYPE CF NEXT GROUP NEXT PAGE 

then this next body group 

01 TYPE DE LINE PLUS 5 

would be printed on value of FIRST 
DETAIL (in PAGE clause) . 

2. If the following body group was the 
last to be printed on a page 

01 TYPE CF NEXT GROUP LINE 12 

and after printing, line-counter =40, 
then this next body group 

01 TYPE DETAIL LINE PLUS 5 

would be printed on line 12 + 1 (i.e., 
line 13) . 



Report Writer Routines 



I 



Floating First Detail 



The first presentation of a body group 
(PH, PF, CH, CF, DE) that contains a 



At the end of the analysis of a report 
description (RD) entry, the Report Writer 
routines are generated, based on the 
contents of the RD. Each routine 
references the compiler-generated card 
number of its respective RD. 
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TABLE HANDLING CONSIDERATIONS 



Subscripts 



If a subscript is represented by a 
constant and if the subscripted item is of 
fixed length, the location of the 
subscripted data item within the table or 
list is resolved during compilation. 

If a subscript is represented by a 
data-name, the location is resolved at 
execution time. The most efficient format 
in this case is COMPUTATIONAL, with a 
PICTURE size less than five integers. 

The value contained in a subscript is an 
integer which represents an occurrence 
number within a table. Every time a 
subscripted data-name is referenced in a 
program, the compiler generates up to 16 
instructions to calculate the correct 
displacement. Therefore, if a subscripted 
data-name is to be processed extensively, 
move the subscripted item to an 
unsubscripted work area, do all necessary 
processing, and then move the item back 
into the table. Even when subscripts are 
described as COMPUTATIONAL, subscripting 
takes time and storage. 



Index-names 



Index-names are compiler-generated 
items, one fullword in length, assigned 
storage in the TGT (Task Global Table) . An 
index-name is defined by the INDEXED BY 
clause. The value in an index-name 
represents an actual displacement from the 
beginning of the table that corresponds to 
an occurrence number in the table. Address 
calculation for a direct index requires a 
maximum of four instructions; address 
calculation for a relative index requires a 
few more. Therefore, the use of 
index-names in referencing tables is more 
efficient than the use of subscripts. The 
use of direct indexes is faster than the 
use of relative indexes. 

Index-names can only be referenced in 
the PERFORM, SEARCH, and SET statements. 



Index Data Items 



Index data items are compiler-generated 
storage positions, one fullword in length. 



that are assigned storage within the COBOL 
program area. An index data item is 
defined by the USAGE IS INDEX clause. The 
programmer can use index data items to save 
values of index-names for later reference. 

Great care must be taken when setting 
values of index data items. Since an index 
data item is not part of any table, the 
compiler is unable to change any 
displacement value contained in an 
index-name when an index data item is set 
to the value of an index-name or another 
index data item. See the SET statement 
examples later in this chapter. 

Index data items can only be referenced 
in SEARCH and SET statements. 



OCCURS Clause 



If indexing is to be used to reference a 
table element and the Format 2 (SEARCH ALL) 
statement is also used, the KEY option must 
be specified in the OCCURS clause. A table 
element is represented by the subject of an 
OCCURS clause, and is equivalent to one 
level of a table. The table element must 
then be ordered upon the key(s) and 
data-name (s) specified. 



DEPENDING ON Option 



If a data item described by an OCCURS 
clause with the DEPENDING ON data-name 
option is followed by nonsubordinate data 
items, a change in the value of data-name 
during the course of program execution will 
have the following effects: 

1. The size of any group described by or 
containing the related OCCURS clause 
will reflect the new value of 
data-name . 

2. Whenever a MOVE to a field containing 
an OCCURS clause with the DEPENDING ON 
option is executed, the MOVE is done 
on the basis of the current contents 
of the object of the DEPENDING ON 
option. 

3. The location of any nonsubordinate 
items following the item described 
with the OCCURS clause will be 
affected by the new value of 



^ffl 
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data-name . If the progranirner wishes 
to preserve the contents of these 
items, the following procedure can be 
used: prior to the change in 
data-name , move all nonsubordinate 
items following the variable item to a 
work area; after the change in 
data-name , move all the item.s back. 

Note : The value of data-name may change 
because a move is made to it or to the 
group in which it is contained; or the 
value of data-name may change because the 
group in which it is contained is a record 
area that has been changed by execution of 
a READ statement. 

For example, assume that the Data 
Division of a program contains the 
following coding: 

01 ANYRECORD. 

05 A PICTURE S999 COMPUTATIONAL- 3. 
05 TABLEA PICTURE S999 OCCURS 100 

TIMES DEPENDING ON A. 
05 GROUPB. 

Subordinate data items. 
End of record. 



as VSAM files, may contain one or more 
OCCURS clauses with the DEPENDING ON 
option. 

This section discusses some factors that 
affect the manipulation of records 
containing OCCURS clauses with the 
DEPENDING ON option. The text indicates 
whether the factors apply to the File or 
Working-Storage sections, or both. 

The compiler calculates the length of 
V-mode records containing the OCCURS clause 
with the DEPENDING ON option at three 
different times, as follows (the first and 
third applies to FD entries only; the 
second to both FD and Working-Storage 
entries) : 

1. When a file is read and the object of 
the DEPENDING ON option is within the 
record. 

2. When the object of the DEPENDING ON 
option is changed as a result of a 
move to it or any item within its 
group. (The length is not calculated 
when a move is made to an item which 
redefines or renames it.) 



GROUPB items are not subordinate to TABLEA, 
which is described by the OCCURS clause. 
Assuming that WORKB is a work area with the 
same data structure as GROUPB, the 
following procedural coding could be used: 

MOVE GROUPB TO WORKB 

Calculate a new value of A 

MOVE WORKB TO GROUPB 

The preceding statements can be avoided 
by placing the OCCURS clause with the 
DEPENDING ON option at the end of the 
record. 

Note : data-name can also change because of 
a change in the value of an itemi that 
redefines or renames it. In this case, the 
group size and the location of 
nonsubordinate items as described in the 
two preceding paragraphs cannot be 
determined. 



For instance before a group item 
with an OCCURS DEPENDING ON clause 
in it can be moved from an I/O 
area to working storage, the 
object of the DEPENDING ON clause 
must be moved separately from the 
I/O area to the corresponding 
area in working storage to force 
initial calculation of the 
receiving field's length. 

If the object of the DEPENDING ON 
option is changed outside of the 
COBOL program, to insure correct 
length, a dummy move of the 
DEPENDING ON object m.ust be made 
upon return to the COBOL program. 

For an output file, after the record 
is written, the length is set to 
maximum to enable a full move of the 
next record to the buffer. 
Immediately after the move, the 
correct length is recalculated as in 
item 2. 



OCCURS CLAUSE WITH THE DEPENDING ON OPTION 



Consider the following example: 
WORKING-STORAGE SECTION. 



If a record description contains an 
OCCURS clause with the DEPENDING ON option, 
the record length is variable. This is 
true for records described in an FD as well 
as in the Working-Storage section. A 
previous chapter discussed four different 
record formats of non-VSAM files. Three of 
them, V-mode, U-mode, and S-mode, as well 



77 CONTROL- 1 
77 WORKAREA-1 



PIC 99. 

PIC 9(6)V99. 



01 SALARY-HISTORY, 

05 SALARY OCCURS TO 10 TIiMES 
DEPENDING ON 
CONTROL-1 PIC 9(6)V99. 
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The Procedure Division statement MOVE 
5 TO CONTROL- 1 will cause a recalculation 
of the length of SALARY-HISTORY. MOVE 
SALARY (5) TO WORKAREA-1 will not cause 
the length to be recalculated. 

The compiler permits the occurrence of 
more than one level- 01 record, containing 
the OCCURS clause with the DEPENDING ON 
option, in the same FD entry (see Figure 
62). For non-VSAM files, if the BLOCK 
CONTAINS clause is omitted, the buffer size 
is calculated from the longest level-01 
record description entry. In Figure 62, 
the buffer size is determined by the 
description of RECORD- 1 ( RECORD- 1 need not 
be the first record description under the 
FD). 



During the execution of a READ 
statement, the length of each level-01 
record description entry in the FD will be 
calculated (see Figure 62). The length of 
the variable portion of each record will be 
the product of the nxameric value contained 
in the object of the DEPENDING ON option 
and the length of the subject of the OCCURS 
clause. In Figure 62, the length of 
FIELD-1 is calculated by multiplying the 
contents of CONTROL-1 by the length of 
FIELD-1; the length of FIELD- 2, by the 
product of the contents of CONTROL- 2 and 
the length of FIELD- 2; the length of 
FIELD- 3 by the contents of CONTROL- 3 and 
the length of FIELD- 3. 



Since the execution of a READ statement 
makes available only one record type (i.e., 
RECORD-1 type, RECORD-2 type, or RECORD- 3 
type), two of the three record descriptions 
in Figure 62 will be inappropriate. In 
such cases, if the contents of the object 
of the DEPENDING ON option does not conform 
to its picture, the, length of the 
corresponding record will be unpredictable. 
For the contents of an item to conform to 
its picture: 

• An item described as USAGE DISPLAY must 
contain external decimal data. 



• An item described as USAGE 
COMPUTATIONAL- 3 must contain internal 
decimal data. 

• An item described as USAGE 
COMPUTATIONAL must contain binary data. 

• An item described as signed must 
contain signed data. 

• An item described as unsigned must 
contain unsigned data. 



The following example illustrates the 
length calculations made by the system when 
a READ statement is executed: 



FD 



01 



01 



RECORD-1. 




05 A PIC 


99. 


05 B PIC 


99. 


05 C PIC 


99 OCCURS 5 TIMES 


DEPENDING ON A. 


RECORD-2. 




05 D PIC 


XX. 


05 E PIC 


99. 


05 F PIC 


99. 


05 G PIC 


99 OCCURS 5 TIKES 



DEPENDING ON F. 



WORKING- STORAGE SECTION. 



01 TABLE- 3. 

05 H PIC99 OCCURS 10 TIMES DEPENDING 
ON B. 

01 TABLE- 4. 

05 I PIC99 OCCURS 10 TIMES DEPENDING 
ON E. 



When a record is read, lengths are 
determined as follows: 



1. The length of C is calculated using 
the contents of field A. The length 
of RECORD- 1=A+B+C. 

2. The length of G is calculated using 
the contents of field F. The length 
of REC0RD-2=D+E+F+G. 

3. The length of TABLE- 3 is calculated 
using the contents of field B. 

U. The length of TABLE- 4 is calculated 
using the contents of field E. 

The programmer should be aware of 
several characteristics of the previously 
cited length calculations. The following 
example illustrates a group item (i.e., 
REC-1) whose subordinate items contain an 
OCCURS clause with the DEPENDING ON option 
and the object of that DEPENDING ON option. 



WORKING- STORAGE SECTION. 
01 REC-1. 

05 FIELD-1 PIC 9. 

05 FIELD- 2 OCCURS 5 TIMES DEPENDING ON 
FIELD-1 PIC X(5) . 
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FD INPUT- FILE 



DATA RECORDS ARE RECORD- 1 RECORD- 2 RECORD- 3. 

01 RECORD- 1. 

05 CONTROL- 1 PIC 99. 

05 FIELD-1 OCCURS TO 10 TIMES DEPENDING ON CONTROL-1 PIC 9(5). 

01 RECORD- 2. 

05 CONTROL- 2 PIC 99- 

05 FIELD-2 OCCURS 1 TO 5 TIMES DEPENDING ON CONTROL-2 PIC 9(4). 

01 RECORD- 3. 

05 FILLER PIC XX- 

05 CONTROL-3 PIC 99- 

05 FIELD-3 OCCURS TO 10 TIMES DEPENDING ON CONTROL-3 PIC X(4). 

Figure 62. Calculating Record Lengths When Using the OCCURS Clause with the DEPENDING ON 
Option 



01 REC-2. 

05 REC-2-DATA PIC X(50). 

The results of executing a MOVE to the 
group item REC-1 will be affected by the 
following: 

• The length of REC-1 may have been 
calculated at some time prior to the 
execution of this MOVE statement. 
The user should make sure that REC-1 
reflects the correct length. 



The length of REC-1 may never have been 
calculated at all, and the result of the 
MOVE will be unpredictable. 



• After the move, since the contents of 
FIELD-1 have been changed, an attempt 
will be made to recalculate the length 
of REC-1. Correct recalculation, 
however, will only be made if the new 
contents of FIELD-1 conform to its 
picture (i.e., USAGE DISPLAY must 
contain an external decimal item, USAGE 
COMPUTATIONAL- 3 must contain an 
internal decimal item and USAGE 
COMPUTATIONAL must contain a binary 
item. An item described as signed must 
contain signed data, and an item 
described as unsigned must contain 
unsigned data) . In the preceding 
example, if FIELD-1 does not contain an 
external decimal item, the length of 
REC-1 will be unpredictable. 

Note ; According to the COBOL description, 
FIELD-2 can occur a maximum of five times. 
If, however, FIELD-1 contains an external 
decimal item whose value exceeds five, the 



length of REC-1 will still be calculated. 
One possible consequence of this invalid 
calculation will be encountered if the 
programmer attempts to initialize REC-1 by 
moving zeros or spaces to it. This 
initialization would inadvertently delete 
part of the adjacent data stored in REC-2. 

The following discussion applies to 
updating a record containing an OCCURS 
clause with the DEPENDING ON option and at 
least one other subsequent entry. In this 
case, the subsequent entry is another item 
containing an OCCURS clause with the 
DEPENDING ON option. 

WORKING- STORAGE SECTION. 
01 VARIABLE-REC. 

05 FIELD-A PIC X(10) . 

05 CONTROL-1 PIC 99. 

05 CONTROL-2 PIC 99. 

05 VARY-FIELD-1 OCCURS 10 TIMES 

DEPENDING ON CONTROL-1 PIC X(5). 
05 TEMP. 

06 VARY-FIELD-2 OCCURS 

10 TIMES DEPENDING ON 
CONTROL-2 PIC X(9) . 

01 STORE-VARY-FIELD- 2. 

05 VARY-FLD-2 OCCURS 10 TIMES 

DEPENDING ON CONTROL-2 PIC X(9). 

Assume that CONTROL-1 contains the value 
5 and VARY-FIELD-1 contains 5 entries. 

In order to add a sixth field to 
VARY-FIELD- 1 the following steps are 
required: 

MOVE TEMP TO STORE -VARY-FIELD-2 . 
ADD 1 TO CONTROL-1. 

MOVE 'additional field' TO VARY-FIELD-1 
(CONTROL-1). 

MOVE STORE -VARY-FIELD-2 TO TEMP. 



i 
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SET Statement 



The SET statement is used to assign 
values to index-names and to index data 
items . 



01 A. 

05 B OCCURS 2 INDEXED BY II, 15- 

10 C OCCURS 2 INDEXED BY 12, 16- 

15 D OCCURS 3 INDEXED BY 13, 14. 
20 E PIC X{20) - 
20 F PIC 9(5). 



When an index-name is set to the value 
of a literal, identifier, or an index-name 
from another table element, it is set to an 
actual displacement from the beginning of 
the table that corresponds to the 
occurrence number indicated by the second 
operand in the statement. The compiler 
performs the necessary calculations. If an 
index-name is set to another index-name for 
the same table, the compiler need make no 
conversion of the actual displacement value 
contained in the second operand- 



However, when an index data item is set 
to another index data item or to an 
index-name, or when an index-name is set to 
an index data item, the compiler is unable 
to change any displacement value it finds, 
since an index data item is not part of any 
table. Thus, no conversion of values can 
take place. Remember this to avoid making 
programming errors - 



For example, suppose that a table has 
been defined as: 



The table appears in storage as shown in 
Figure 63. 



Suppose that a reference to D (2, 2, 3) 
is necessary- The following method is 
incorrect: 

SET 13 TO 2. 

SET INDX-DATA-ITM TO 13- 

SET 13 UP BY 1. 

SET 12, II TO INDX-DATA-ITE. 

MOVE D (II, 12, 13) TO WORKAREA. 

The value contained in 13 after the first 
SET statement is 25, which represents the 
beginning point of the second occurrence of 
D. When the second SET statement is 
executed, the value 25 is placed in 
INDX-DATA-ITM, and the fourth SET statement 
moves the value 25 into 12 and II, The 
third SET statem.ent increases the value in 
13 to 5 0. The calculation for the address 
D (II, 12, 13) would then be as follows: 

(address of D (1, 1, 1)) + 25 + 25 + 50 
= (address of D (1, 1, 1)) + 100 

This is not the address of D (2, 2, 3). 



B(1) 



B(2) 



C (1, 1) 



C (1, 2) 



C (2, 1) 



C (2, 2) 



D 




1, 


1) 


D 




1, 


2) 


D 
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3) 


D 


[1, 


2, 
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^2, 


2. 
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Byte 

-I 

-! 25 

H 50 

-! 75 

H 100 

H 125 

H 150 

^ 175 

H 200 

H 225 

H 250 

^ 275 

-• 300 



Figure 63. Table Structure in Virtual Storage 
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The following method will find the 
correct address: 

SET 13 TO 2. 

SET 12, II TO 13. 

SET 13 UP BY 1. 



(address of D (1, 1, 1)) + 150 +75+50 i 
= (address of D (1, 1, 1)) + 275 ' 



The rules for the SET stateirent are 
shown in Table 33. 



In this case, the first SET statement 
places the value 25 in 13. Since the 
compiler is able to calculate the lengths 
of B and C, the second SET statement places 
the value 75 in 12, and the value 150 in 
II. The third SET statement places the 
value 50 in 13. The correct address 
calculation will be: 



Use care when setting the value of 
index-names associated with tables 
described as OCCURS DEPENDING ON. If the 
table entry length is changed, the value 
contained within the index-name will become 
invalid unless a new SET statement corrects 
it. 
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Table 33. Rules for the SET Statement 

-T 



T ^ 

Identifier or Literal 



Sending 



Receiving 



Index-name 



Index data item 



Index-name 



Set to value 
corresponding to 
occurrence number^ 



Move without 
conversion 



Set to value corre- 
sponding to occurrence 
number 



Index data item 



Move without 
conversion 



Move without 
conversion 



Illegal 



Identifier 



Set to occurrence 
number represented 
by index-name 



Illeqal 



Illegal 



I ^If index-names refer to the same table element, move without conversion. 

L 
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SEARCH Statement 



Only one level of a table (a table 
element) can be referenced with one SEARCH 
statement- Note that SEARCH statements 
cannot be nested, since an imperative- 
statement must follow the WHEN condition, 
and the SEARCH statement is itself 
conditional. 

TO write a series of statements that 
will search the 3-dimensional table defined 
in the discussion of the SET statement, the 
programmer could write: 



The PERFORM statement varies the indexes 
(II and 12) associated with table elements 
B and C; the SEARCH statement varies index 
13 associated with table element D. 



The values of II and 12 that satisfy the 
WHEN conditions of the SEARCH statement are 
saved in 15 and 16. II and 12 are then 
both set to 3, so that upon return from the 
SEARCH statement, control will fall through 
the PERFORM statement to the GO TO 
statement. 



Subsequent references to the desired 
occurrence of table elements E and F make 
use of the index-names 15 and 16 in which 
the correct value was saved. 



77 COMPARANDl PIC X(5). 
77 C0MPARAND2 PIC 9(5). 

01 A. 

02 B OCCURS 2 INDEXED BY II I5. 

03 C OCCURS 2 INDEXED BY 12 16. 

04 D OCCURS 3 INDEXED BY 13 14. 
05 E PIC X(5). 
05 F PIC 9(5). 



(Initialize COMPARANDl and C0MPARAND2) 

PERFORM SEARCH-TESTl THRU SEARCH-EXITl 
VARYING II FROM 1 BY 1 UNTIL 12 IS 
GREATER THAN 2. 
ENTRY- NO ENTRYl. 

GO TO ERROR-RECOVERYl . 

SEARCH-TESTl. 
SET 13 TO 1. 
SEARCH D WHEN E (II, 12, 13) = 

COMPARANDl AND F (II, 12, 13) = 

C0MPARAND2 
SET 15 TO II 
SET 16 TO 12 
SET 12 TO 3 
SET II TO 3 
ALTER ENTRY- NOENTRYl TO PROCEED 

TO ENTR Y- PROCESS I NGl- 
SEARCH-EXITl. EXIT. 



Since a SEARCH verb results in the 
examination of the individual elements 
in the named table, the XREF or SXREF 
for a SEARCH will reference the element 
name for the table rather than the table 
itself. LISTER could provide the source 
cross-reference material that might be 
desired. 



Format 1 SEARCH statements perform a 
serial search of a table. If it is certain 
that the "found" condition is beyond some 
intermediate point in the table, the 
index-names can be set at that point and 
only that part of the table be searched; 
this speeds up execution. If the table is 
large and must be searched from the first 
occurrence to the last. Format 2 (SEARCH 
ALL) is more efficient than Format 1, since 
it uses a binary search technique; however, 
the table must then be ordered. 



In Format 1, the VARYING option allows 
the programmer to: 



• Vary an index-name other than the first 
index-name stated for this table 
element. Thus, with two SEARCH 
statements, each using a different 
index-name, more than one value can be 
referenced in the same table element 
for comparisons, etc. 



ERROR-RECOVERYl . 



ENTRY- PROCESSINGl . 
MOVE E (15, 16, 
MOVE F (15, 16, 



13) TO OUTAREAl. 
13) TO 0UTAREA2. 



Vary an index-name from another table 
element. In this case, the first 
index-name specified for this table is 
used for the SEARCH, and the index-name 
specified in the VARYING option is 
incremented at the same time. Thus, 
the programmer can search two table 
elements at once. 
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SEARCH ALL Statement 



The SEARCH ALL Statement is used to 
search an entire table for an item without 
having to write a loop procedure. For 
example, a programmer-defined table may be 
the following: 

01 TABLE. 

05 ENTRY- IN-TABLE OCCURS 90 TIMES 
ASCENDING KEY-l,KEY-2 



DESCENDING 


KEY- 3 




INDEXED BY 


INDEX-1. 




10 PART-1 


PICTURE 


9(2). 


10 KEY-1 


PICTURE 


9(5). 


10 PART- 2 


PICTURE 


9(6). 


10 KEY- 2 


PICTURE 


9(4). 


10 PART- 3 


PICTURE 


9(33) 


10 KEY- 3 


PICTURE 


9(5). 



keys. The primary and secondary keys 
(KEY-1 and KEY-2) are in ascending order 
whereas the least significant key (KEY-3) 
is in descending order. If an entry is 
found in which the three keys are equal to 
the given values (i.e., VALUE-1, VALUE-2, 
VALUE-3), PART-1 of that entry will be 
moved to OUTPUT-AREA. If matching keys are 
not found in any" of the entries in TABLE, 
the NOENTRY routine is entered. 

If a match is found between a table 
entry and the given values, the index 
(INDEX-1) is set to a value corresponding 
to the relative position within the table 
of the matching entry. If no match is 
found, the index remains at the setting it 
had when execution of the SEARCH ALL 
statement began. 



A search of the entire table can be 
initiated with the following instruction: 

SEARCH ALL ENTRY- IN-TABLE AT END GO TO 
NOENTRY WHEN KEY-1 (INDEX-1) = VALUE- 1 
AND KEY-2 (INDEX-1) = VALUE- 2 AND KEY-3 
(INDEX-1) = VALUE-3 MOVE PART-1 
(INDEX-1) TO OUTPUT-AREA. 

The preceding instructions will execute 
a search on the given array TABLE, which 
contains 90 elements of 55 bytes and 3 



Note: It is more efficient to test keys in 
order of significance (i.e., KEY-1 should 
be specified before KEY-2 in the WHEN 
statement) . The WHEN statement can only 
test for equality, and only one side of the 
equation may be a key. 

In Format 2 , the SEARCH ALL statement, 
the table must be ordered on the key(s) 
specified in the OCCURS clause. Any key 
may be specified in the WHEN condition, but 
all preceding data-names in the KEY option 
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In Format 1, the WHEN condition can be 
any relation condition and there can be 
more than one. If multiple WHEN conditions 
are stated, the implied logical connective 
is OR — that is, if any one of the WHEN 
conditions is satisfied, the imperative- 
statement following the WHEN condition is 
executed. If all conditions are to be 
satisfied before exiting from the SEARCH, 
the compound WHEN condition with AND as the 
logical connective must be written. 



SEARCH ALL Statement 



The SEARCH ALL statement is used to 
search an entire table for an item without 
having to write a loop procedure. For 
example, a programmer-defined table may be 
the following: 



01 



In Format 2 , the SEARCH ALL statement. 



^^^ v-'ju v-t^^i^i. c;»^ 



TABLE. 






05 ENTRY- IN-TABLE OCCURS 90 TIMES 


ASCENDING KEY-l,KEY-2 


DESCENDING 


KEY- 3 


INDEXED BY 


INDEX-1. 


10 


PART-1 


PICTURE 9(2). 


10 


KEY-1 


PICTURE 9(5). 


10 


PART- 2 


PICTURE 9(6). 


10 


KEY- 2 


PICTURE 9(4). 


10 


PART- 3 


PICTURE 9(33). 


10 


KEY- 3 


PICTURE 9(5). 



A search of the entire table can be 
initiated with the following instruction: 

SEARCH ALL ENTRY- IN-TABLE AT END GO TO 
NOENTRY WHEN KEY-1 (INDEX-1) = VALUE-1 
AND KEY- 2 (INDEX-1) = VALUE- 2 AND KEY- 3 
(INDEX-1) = VALUE- 3 MOVE PART-1 
(INDEX-1) TO QUTPUT-A^REA. 

The preceding instructions will execute 
a search on the given array TABLE, which 
contains 90 elements of 55 bytes and 3 
keys. The primary and secondary keys 
(KEY-1 and KEY-2) are in ascending order 
whereas the least significant key (KEY-3) 
is in descending order. If an entry is 
found in which the three keys are equal to 
the given values (i.e., VALUE-1, VALUE-2, 
VALUE-3), PART-1 of that entry will be 
moved to OUTPUT-AREA. If matching keys are 
not found in any of the entries in TABLE, 
the NOENTRY routine is entered. 

If a match is found between a table 
entry and the given values, the index 
(INDEX-1) is set to a value corresponding 
to the relative position within the table 
of the matching entry. If no match is 
found, the index remains at the setting it 
had when execution of the SEARCH ALL 
statement began. 



specified in the OCCURS clause. Any key 
may be specified in the WHEN condition, but 
all preceding data-names in the KEY option 
must also be tested. The test must be an 
"equal to" (=) condition, and the KEY 
data-name must be either the subject or 
object of the condition, or the name of a 
conditional variable with which the tested 
condition-name is associated. The WHEN 
condition can also be a compound condition, 
formed from one of the simple conditions 
listed above, with AND as the only logical 
connective. The KEY data item and the item 
with which it is compared must be 
compatible, as given in the rules of the 
relation test. 



Compilation is faster if keys are tested 
in the SEARCH statement in the same order 
as they appear in the KEY option. 



Note that if KEY entries within the 
table do not contain valid values, then the 
results of the binary search will be 
unpredictable. 



Building Tables 



When reading in data to build an 
internal table: 



1. Check to make sure the data does not 
exceed the space allocated for the 
table. 

2. If the data must be in sequence, check 
the sequence. 

3. If the data contains the subscript 
that determines its position in the 
table, check the subscript for a valid 
range. 

4. If a fixed-length table is defined 
larger (for example, 150 entries) 
than the actual data supplied 
(for example, 100 data entries), 
then the table must be initialized 
to high value for ascending search 
or low value for descending search. 

When testing for the end of a table, use 
a named value giving the item count, rather 
than using a literal. Then, if the table 
must be expanded, only one value need be 
changed, instead of all references to a 
literal. 




Note : It is more efficient to test keys in 
order of significance (i.e., KEY-1 should 
be specified before KEY-2 in the WHEN 
statement) . The WHEN statement can only 
test for equality, and only one side of the 
equation may be a key. 
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LISTER FEATURE 



This chapter describes the lister 
feature, a major new facility for 
optionally producing reformatted source 
listings with expanded, embedded cross 
referencing information to increase 
intelligibility and conserve space. Topics 
discussed in this chapter include: 



• Overall operation of the lister feature 



• The output source listing 



• The output summary listing 



• The optional reformatted output deck 



• Using the lister feature 

Features of the new source listing 
include: 

• Standard indentation for all Data 
Division level numbers to show group 
structure, and for all IF statements 
and the like in the Procedure Division 
to show program logic. 

• Alignment of PICTURE arid VALUE clauses 
to highlight OCCURS and REDEFINES 
clauses. 

• Two-way, embedded cross-references to 
eliminate indirect "lookups" (via a 
separate conventional SXREF listing) . 

• Reference letters to show the type of 
reference, indicate overall usage of a 
program item, and reduce the need to 
look up each reference. 

• Footnotes on Procedure Division pages 
to show the definition of referenced 
data items, thereby eliminating more 
"lookups" . 

• Two-column Procedure Division pages to 
compact the listing and further reduce 
page turning. 

• Cross-reference summary to show how, 
and how much, FD's and Procedure 
Division section's reference each 
other. 

• Optional reformatted and renumbered 
source deck for manual use or for 
updating the BASIS library. 



OVERALL OPERATION OF THE LISTER 



The lister accepts source programs 
written in American National Standard COBOL 
and analyzes the source statements to 
establish inter-statement references, as 
well as the type of action resulting from 
the reference such as redefinition, 
interrogation, open/close, etc. After 
scanning the source statements, the lister 
performs all information transfers 
necessary for cross-referencing. Finally, 
the lister composes and prints the 
reformatted source code. 

This reformatted source output follows 
indenting conventions imposed by the lister 
to increase readability, and contains cross 
references between data items and Procedure 
Division statements, between PERFORM 
statements and paragraph names, etc. 
Optionally, the lister produces a new 
source deck that matches the output listing 
except that the embedded cross-reference 
information is omitted. 

Thus, the lister can be used to process 
source decks for uniformity of indenting 
and for highlighting of IFs, GO TOs, etc., 
or it can be used simply to obtain a 
cross-referenced source listing as 
permanent documentation of a production 
program, or as an aid in program analysis 
and debugging. Various options perm.it 
printing the Procedure Division listing in 
two columns to conserve space, and 
inclusion of BASIS and COPY statements. 
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The Listing 



The reformatted output listing is 
divided into four parts: 

1. A one-page introduction which 
describes briefly lister codesj, 
conventions, uses 

2. The Identification and Environment 
divisions 

3. Detailed, cross-referenced, 
reformatted Data and Procedure 
divisions 

H. The summary listing 

These are described briefly below, and 
in greater detail in subsequent sections. 
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The Output Deck 



The deck produced optionally by the 
lister may be saved either in card form or 
in a BASIS library- This output reflects 
the output listing, except that 
cross-reference information is omitted, and 
that card numbers replace statement 
numbers. The output deck is described in 
detail in a subsequent section of this 
chapter. 



The most striking change in the 
appearance of the Data Division listing is 
the addition, at the right of each 
statement, of cross references that 
identify the statement number of each Data 
Division or Procedure Division statement 
that redefines, changes, reads, tests, or 
otherwise refers to the data item. When 
the number of such references is too great 
to fit on the line, the lister prints as 
many on the line as there is space for, and 
prints the remainder as a footnote at the 
bottom of the page. 



Reformatting of Identification and 
Environment Divisions 



The lister reformats the Identification 
Division statements only by imposing 
indenting conventions- Statements are 
indented two spaces. Statemients with 
continuations are indented four spaces. 

Environment Division statements are 
reformatted by imposing indenting 
conventions and by appending 
cross-reference information to SELECT 
statements in the FILE CONTROL section. 
Thus, in reading the FILE CONTROL section, 
you receive direct references to the FILE 
DESCRIPTION Statements in the Data 
Division. 



Data Division Reformatting 



Procedure Division Reformatting 



The lister reformats the Procedure 
Division by applying indenting conventions 
to nested IFs, GO TOs, etc., and by 
appending cross references to sections and 
paragraphs, where appropriate, to indicate 
that the procedure is PERFORMed by another 
or similar action. It also appends 
references to the Data Division so that the 
data item being acted upon can be found 
quickly. Six codes are used in the 
Procedure Division: 



A ALTER 

B (ALTER) to PROCEED TO 

E INPUT or OUTPUT procedure for 

Sort/Merge 

G GO TO 

P PERFORM 

T (PERFORM) THRU 



The lister reformats the Data Division 
statements principally by imposing 
indenting conventions on them. In 
addition, it aligns PICTURE, VALUE, and 
other clauses vertically to improve 
readability and facilitate visual checking. 
This alignment generally highlights 
REDEFINES and OCCURS clauses, for exam.ple. 
All indenting is with respect to the left 
margin, which contains the statement 
number. The indenting conventions are: 

• FDs are not indented 

• For LEVEL 01 items, the indent is two 
spaces 

• For LEVEL 02 items, indent is four 
spaces 



Summary Listing 



The summary listing provides an overall 
view of the relationship among FDs, RDs, 
and SDs in the program^ The entry for each 
of these major parts of the program 
consists of a title line showing the 
statement number and the name of the file, 
record, or section and a series of counts 
(by reference type) for each of the 
categories "intra", "from", and "to". 
Intra references are those within the 
section, file, or record, such as REDEFINES 
and PERFORM operations. 



Level 03 and lower items are each 
indented two from the last higher level 
item. Using this convention, the overall 
structure of each file and group item is 
immediately apparent when reading the 
listing. Level 77 items are not indented. 
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THE SOURCE LISTING 



• Verbs 



General Appearance 



In looking at the source listing of the 
Identification, Environment, or Data 
Divisions, you will find that the pages may 
be considered as having three "columns". 
The leftmost contains a statement number, 
or is blank if the line is either a comment 
or a continuation of the preceding 
statement or line- The second column 
contains the reformatted COBOL statements. 
The third (not present in the Procedure 
Division) contains references to or from 
other statements in the source program. 
Thus, each line of the output listing 
contains a numbered source statement or its 
continuation, and a reference or series of 
references to all other statements in the 
source program that refer to it. If the 
series of references is too long to file on 
the line, the lister prints as many as will 
fit, followed by a letter indicating a 
footnote- The footnote contains the 
remainder of the references. 

The source listing of the Procedure 
Division is normally printed in 
double-column format, with each column 
divided as described above. This format 
also approximately doubles the span of 
logic that can be seen on one page or one 
facing-page spread. 

Another characteristic of the source 
listing is that regardless of whether the 
source code follows indentation 
conventions, the lister indents statements 
according to their type, and according to 
hierarchy, where applicable. This feature 
of the lister makes file and record 
structure immediately visible, and also 
helps to identify groups of related 
statements such as IF/ELSE and nesting of 
IFs. 



Format Conventions 



• ELSE statements 

• OTHERWISE statements 

• AT END Statements (only when following 
SEARCH statements) 

Indentation of the new statement is made 
according to the following rules: 

1. Data Division 

• FDs and Level 77 items are not 
indented 

• Level 01 items are indented two 
spaces in the FILE SECTION or REPORT 
SECTION and are not indented in the 
LINKAGE or WORKING- STORAGE sections 

• Each subsequent lower level within 
an 01 item is indented two spaces 
more than the preceding higher level 

2. Procedure Division 

• Section names are not indented 

• Paragraph names are indented two 
spaces 

• Unconditionally-executed verbs are 
indented four spaces 

• Verbs executed under a single 
condition such as IF or AT END are 
indented six spaces 

• The first IF statement in a nest of 
IF statements is indented two 
spaces; subsequent nested IF 
statements are indented an 
additional two spaces at each level 

• ELSE statements are indented to the 
same position as the IF statement to 
which they refer 

3. Continuation lines (in all divisions) 
are indented six spaces with respect 
to the first line of the continued 
statement 






New statements are indented from the 
left margin, which contains the statement 
number- The lister treats as new 
statements 

• Division headers 

• Section headers 

• Paragraph names 

• Level numbers 



Word spacing within a statement and on 
continuation lines is usually one space. 
Within the Data Division, however, PICTURE 
and VALUE clauses are aligned as nearly as 
possible into columns so that they may be 
found and compared easily. 

Words are not split at the end of a 
statement or continuation line unless the 
word to be split is a nonnumeric literal 
that will not fit on a single continuation 
line- 
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References appear to the right of the 
statement or continuation line. References 
following paragraph names appear 
immediately to the right of the name, 
separated by a blank. References following 
other types of statements appear as far to 
the right as possible depending on the 
number of blanks available on the line. 
Each reference consists of a statement 
number and a type indicator- References in 
series are separated by commas, and are in 
ascending order- 



Within the Data Division, a reference 
may also be an alphabetic footnote 
indicator. The footnote contains a series 
of references to REDEFINES and Procedure 
Division statements that refer to that data 
item. 

Within the Procedure Division, the 
reference may also be a footnote indicator, 
but the footnote is different in 
appearance- In the Procedure Division, the 
footnote is actually an on-page replica of 
the Data Division statement referred to by 
the footnoted statement. This replica is 
complete with all other references to the 
data item from other portions of the 
program. To conserve space in the listing, 
the lister does not repeat a footnote if it 
appears at the bottom of either of the two 
preceding pages. 



Type Indicators 



As mentioned above, a reference consists 
of a statement number and a type indicator. 
The type indicator provides immediate 
information as to what is being done by the 
statement referred to. 

Two sets of type indicators are used by 
the lister, one for the Data Division, and 
one for the Procedure Division. Within the 
Data Division, the type indicators are: 

U Data item unchanged (used as a 
source field) 

C Data item changed (such as ADD or 

MOVE) 

E Data item referred to by Environment 
Division statement (SELECT) or by 
Procedure Division input/output 
operation (READ, WRITE) 

D Data item REDEFINED or RENAMEd 

Q Queried by IF, WHEN, or UNTIL 

R Referred to by a READ statement 



W Referred to by a WRITE, GENERATE, 
DISPLAY, or similar statement 

X Used as an index, subscript, or 
object of a ©EPENDING ON statement 

Within the Procedure Division, the type 
indicators are: 

A ALTER 

B (ALTER) TO PROCEED TO 

E INPUT or OUTPUT procedure (Sort or 

Merge feature) 

G GO TO 

P PERFORM 

T (PERFORM) THRU 



THE SUMMARY LISTING 



The summary listing is useful both as an 
analysis and as a troubleshooting aid. 
Using the summary listing, the data areas 
most referred to, the procedures that 
reference them most often and the nature of 
those references can be ascertained 
quickly. The number of references to 
undefined symbols and the num.ber of 
incorrectly coded COBOL words can also be 
ascertained. 

General Appearance 



Each division or section header, and 
each FD, RD, or SD begins a new entry in 
the summary listing. The entry consists of 
the header line and, beginning on the next 
line, the total number of each kind of 
reference to that section from within 
itself (INTRA) , and from outside itself 
(FROM) . These references are followed by 
similar information for references the 
section makes to others outside itself 
(TO). 

THE OUTPUT DECK 



By specifying the DECK option on the LST 
card, a new COBOL source deck can be 
produced that reflects the reformatted 
source listing. This deck may be saved in 
a BASIS library (used directly as input to 
the compiler) or punched onto cards. 
Because of reformatting, the new deck may 
contain more cards than the original, but 
the difference is not great enough to cause 
any appreciable increase in compilation 
time. The output deck differs from the 
listing as follows: 

1. References, footnotes, and blank lines 
are omitted. 

2. Literals will be repositioned, if 
needed, to assure proper continuation. 
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3. Statement numbers are converted to 
card numbers - 

a. The statement number is multiplied 
by 10, and leading zeros are added 
as necessary to fill columns 1 
through 6 . 

b. Comment and continuation cards are 
numbered one higher than the 
preceding card. 

c. Statement-beginning cards are 
given the higher of the two 
numbers produced by the first two 
rules. 

The new deck will permanently process 
all the BASIS INSERT and DELETE cards, and 
thus can be used to permanently update the 
Source Statement Library. This avoids 
having to resequence the update cards after 
they have been tested, and avoids the 
errors incurred during that resequencing 
process. 



USING THE LISTER 



Options 



The format and contents of the listings 
and deck produced by the lister are 
determined by the options specified on the 
LST card. The LIST card may be placed 
anywhere between the EXEC statement and the 
first statement of the COBOL program. It 
may be placed between any other compiler 
option cards. 

Two format options determine the 
dimensions and layout of the source and 
summary listings. 

PROC=lcol 
2col 

specifies that the source listing of 
the Procedure Division will be printed 
in either single or double column 
format. At least 132 print positions 
are required for double column format. 

Three options pertain to the output 
deck: 



DECK 
NODECK 



indicates whether an updated source 
deck is to be produced as a result of 
the lister reformatting and/or the 
update basis library. 



COPYPCH 
NOCOPYPCH 



will punch updated and reformatted 
copy libraries as a permanent part of 



the source when DECK is specified, and 
will punch out an updated and 
reformatted copy library when no 
updated source deck is requested. 

LSTONLY 

LSTCOMP 

The LSTONLY Option will give a 
reformatted listing and a deck, if 
DECK was specified, but will not 
compile the program. LISTCOMP will, 
in addition to listing the source, 
also compile the program as part of 
the iob step. 



PROGRAMMING CONSIDERATIONS 



The lister is designed to operate most 
efficiently on syntactically correct COBOL 
source, and does not have the expanded 
error handling of the full compiler. It is 
therefore highly recommended that the user 
programs first be compiled using the SYNTAX 
option, and syntax errors corrected before 
invoking the lister feature. If the lister 
function is used and there are syntactical 
errors, the formatting may be 
unpredictable, and performance can be 
significantly impacted. 

Unusual termination of lister can occur if 
the source program contains : 

• Too many (approximately 80 or more) 
consecutive {*) comment cards. 

• Too many (approximately 100 or more) 
consecutive blank cards. 



Further notes ; Since Lister reformats the 
users COBOL program, compilation of the 
program, if LSTCOMP is in effect, will be 
different from a non-lister compilation of 
the same program. For example: 

1. Lister sequence numbers may be 
different 

2. SKIP/EJECT cards will have no 
functional value with LISTER 

3. BASIS card will be dropped from the 
Lister listings 

4. FIPS messages will be based on the 
reformatted Lister listings. 

5. Suppress option of COPY will have no 
effect 

6. Sequence checking will not take place 
for a Lister sum. 

7. The Insert card indicator for BASIS 
will not be indicated on a lister 
listing. 



^m 
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SYMBOLIC DEBUGGING FEATURES 



A prograitiitier using IBM DOS/VS COBOL 
under the DOS/VS System, has several 
methods available to him for testing and 
debugging his programs. Use of the 
symbolic debugging features is the easiest 
and most efficient method for testing and 
debugging and is described in detail in 
this chanter- 

The chapter entitled "Program Checkout" 
contains information useful for testing and 
debugging programs run without the symbolic 
debugging features. It also contains 
information on compile-time debugging 
features, linkage editor and execution-time 
diagnostics as well as a description of 
taking checkpoints and restarting programs. 

The chapter entitled "Execution 
Statistics" also contains information 
helpful in testing and debugging programs 
run both with and without the symbolic 
debugging features. 



USE OF THE SYMBOLIC DEBUGGING FEATURES 



There are three symbolic debugging 
options available to the programmer for 
object-time debugging: the statement 
number option, the flow trace option, and 
the symbolic debugging option. None of 
these features require source language 
coding; rather they are requested via the 
CBL card at compile time. Operation of the 
symbolic debug option is dependent upon 
execution-time control cards. Figure 9 
illustrates the output generated for each 
of these features. 



execution-time run unit. The CBL card is 
discussed in detail in the chapter 
"Preparing COBOL Programs for Processing.' 



FLOW TRACE OPTION 



The flow -trace option provides the 
programmer with the facility for receiving 
a formatted trace (i.e., a list containing 
the program identification and statement 
nimibers) corresponding to a variable number 
of procedures executed prior to an abnormal 
termination. The number of procedures to 
be traced is specified by the programmer. 
If the FLOW option is specified and the 
number of procedures is not specified, a 
trace of 99 procedures is provided. 

A flow trace is printed only in the 
event of an abnormal termination. It is 
requested at compile time via the FLOW 
option of the CBL card. In a subprogram 
structure, once a FLOW specification has 
been made on a program, the subprograms for 
which a trace is desired should specify 
FLOW=0. The FLOW=0 specification enables 
subprograms to utilize the table space 
reserved previously for the trace; 
additional table space need not be 
allocated. 

FLOW and STXIT, and FLOW and OPT are 
mutually exclusive options at compile-time 
and FLOW and STXIT are mutually exclusive 
in an execution-time run unit. The CBL 
card is discussed in the chapter "Preparing 
COBOL Programs for Processing." 




STATEMENT NUMBER OPTION 



SYMBOLIC DEBUG OPTION 



The statement niomber option facilitates 
debugging by providing the programmer with 
information about the statemient being 
executed at the time of an abnormal 
termination of a job. It identifies the 
program containing the statement and 
provides the number of the statement and of 
the verb being executed. 

This feature is requested at compile 
time via the STATE option of the CBL card. 
Note that STATE and STXIT, STATE and 
SYMDMP, and STATE and OPT are mutually 
exclusive options at compile-time and STATE 
and STXIT are mutually exclusive in an 



Thfc symbolic debug option produces a 
symbolic formatted dump of the object 
program's data area when the program 
abnormally terminates. It also enables the 
programmer to request dynamic dumps of 
specific data-names at strategic points 
during program execution- If two or more 
COBOL programs are link edited together and 
one of them terminates abnormally, the 
program causing termination and any callers 
compiled with the symbolic debug option, up 
to and including the main program, will be 
given a formatted dump. If any called 
program contains the SYMDMP option, the 
main program must be an ANS COBOL program - 
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Another feature of SYMDI^F is that a 
check is made for a subscript which points 
out of the program area and for the length 
of a variable-length move out of the data 
area. If these address limits are reached, 
message C170I is issued and an abend dump 
is given. 



placed in the input stream, 
are discussed below. 



Object-Time Control Cards 



"hese cards 



The abnormal termination dump consists 
of the following parts : 

1. Abnormal termination message, 
including the number of the statement 
and of the verb being executed at the 
time of an abnormal termination. 

2. Selected. areas in the Task Global 
Table. 

3. Formatted dump of the Data Division 
including: 

(a) for an SD, the statement niimber, 
the sort-file-name, the type, and 
the sort record. 

(b) for an FD, the statement number, 
the file-name, the type, SYSnnn, 
DTF status, the contents of the 
Pre-DTF and DTF in hexadecimal, 
and the fields of the record. 

for a VSAM file, the file-name, 
whether the file is open or 
closed, file organization, type of 
access, type of last input-output 
statement, the current contents of 
the FILE STATUS word, as well as 
the record fields. 

(c) for an RD, the statement number, 
the report-name, the type, the 
report line, and the contents of 
PAGE-COUNTER and LINE-COUNTER if 
present. 

(d) for an index-name, the name, the 
type, and the occurrence number in 
decimal. 

Note: For DTFDA when ACCESS IS 
RANDOM, the actual key is not provided 
in the Pre-DTF. 

The symbolic debug option is requested 
at compile time via the SYMDMP option of 
the CBL card. Note that SYMDMP and STXIT, 
SYMDMP and STATE, and SYMDMP and OPT are 
mutually exclusive options at compile time 
and SYMDMP and STATE and STXIT are mutually 
exclusive in a single execution-time run 
unit. The CBL card is discussed in the 
chapter "Preparing COBOL Programs for 
Processing. " 

Operation of the symbolic debug option 
is dependent on object-time control cards 



The operation of the symbolic debug 
option is determined by two types of 
control cards : 

Program- control card — required if 
abnormal termination and/or dynamic 
dumps are requested. 

Line-control card — required only if 
dynamic dumps are requested. 

Syntax Rules : The fields of both the 
program- control card and the line-control 
card must conform to the following rules: 

1. Control cards are essentially free 
form, i.e., parameters coded on these 
cards can start in any column. 
However, parameters may not extend 
beyond column 71. 

2. Each parameter except the last must be 
immediately followed by a comma. 

3. No commas are needed to account for 
optional parameters that are not 
specified. 

4. All upper-case letters represent 
specifications that are to appear in 
the actual statement exactly as shown. 

5. All lower-case letters represent 
generic terms that are to be replaced 
in the actual statement. 

6. Brackets are used to indicate that a 
specification is optional and is not 
always required in the statement. 

7. Brackets enclosing stacked items 
indicate that a choice of one item 
may, but need not, be made by the 
programmer. 

8. Braces enclosing stacked items 
indicate that a choice of one item 
must be made by the prograirmer. 

9. All punctuation marks and special 
characters shown in the statement 
formats other than hyphens, brackets, 
braces, and underscores, must be 
punched exactly as shown. This 
includes commas, parentheses, and the 
equal sign. 

10. Underscoring indicates the default 
case. 
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Continuation Cards ; To continue either the 
program- control card or the line-control 
card, a nonblank character must be coded in 
column 7 2 of the continued card. 



4 
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Individual keywords and data-names cannot 
be split between cards. 

Control Statement Placement : The placement 
of the control cards in the input stream 
must be as follows : 



program-id, nnn 

,SD[=filename] 
,MT[=filename] 



ENTRY 
NOENTRY 



, (HEX) 

, (NOHEX) 



1- 



If a main program is compiled with the 
SYMDMP option, the control cards must 
precede the programmer's data, if any, 
in the input stream: 

// EXEC 



rr'^»^4--^/-.i 



/* 



/* 



{ Programmer ' s Data } 



If the main program is compiled 
without the SYMDMP option, but at 
least one subprogram has been 
compiled with the SYMDMP option, 
then two alternatives exist: 



a. 



If all data card files have 
reached EOF before the 
subroutine compiled with 
SYMDMP is called, then the 
following sequence should 
be used: 



// 



/* 



EXEC 

(programmer's Data for 
Main Program] 

[control Cards] 



b. 



If calls to the subroutine 
compiled with SYMDMP are 
interspersed with reading 
of card files, then a dummy 
subroutine, consisting of 
only an EXIT PROGRAM 
statement and compiled with 
the SYMDMP option, should be 
called as the first statement 
of the main program. The 
placement of control cards is 
as follows: 

// EXEC 

[control Cards] 

/* 

[Programmer ' s Data] 

/* 
/£ 



Program- Control Cards ; A program- control 
card must be present at execution time for 
any program requesting a SYMDMP service. 
Program-control cards have the following 
format : 



program- id 

is a one through eight character COBOL 
program- name. This program-name must 
be the name of a COBOL program 
compiled with the SYMDMP option. This 
parameter is required and must appear 
first on the program-control card. 



is a 3-digit integer representing the 
programmer logical unit assigned to 
the dictionary file produced at 
compile time {i.e., the SYS005 file.) 
This parameter is required and must 
follow the "program-id". This value 
must be the same as the one specified 
in the ASSGN control statement for the 
dictionary file at execution time. 

SD[=f ilename] 

MT[=f ilename] 

SD must be specified if the symbolic 
unit indicated by "nnn" is a disk 
file; MT must be specified if it is a 
tape file. "filename" is the name of 
the dictionary file produced at 
compile time. For a tape file, the 
"filename" parameter is ignored. For 
a disk file, if "filename" is not 
specified, IJSYS05 will be used, 
"filename" may be from one to seven 
characters in length. If "filename" 
is specified on the CBL card for a 
disk file, "filename" must also be 
specified on the program-control card 
and these names must be identical. 






ENTRY 
NOENTRY 



ENTRY is used to provide a trace of a 
program- name when several programs are 
link edited together- Each time the 
program whose PROGRAM- ID matches the 
"program-id" parameter is entered, its 
name is displayed. 



(HEX) 
(NOHEX) 



refers to the format of the Data 
Division area provided in the abnormal 
termination dump. If HEX is 
specified, level- 01 items are provided 
in hexadecimal. Items subordinate to 
level- 01 items are printed in EBCDIC, 
if possible. Level-77 items are 
provided both in EBCDIC and 
hexadeciuial. If HEX is not specified, 
items subordinate to level-01 items 
and level-77 items are provided in 
EBCDIC. If unprintable, hexadecimal 
notation is provided. 
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Note ; Parentheses are required. 



Line-Control Cards : Line-control cards 
have the following format: 



line-nuin [ , (verb-num) ] [ ,0N n][,ni][,k] 



r, (HEX) 1 
[, ( NOHEX ) J , 



ALL 



{[ 



, (HEX) 1 

, (NOHEX) J , namel (THRU nanie2] 



..} 



line-nuip 

corresponds to the generated card 
number prior to which the dump is 
desired. The dump is given before the 
first or only verb on that line. This 
parameter is required and must be the 
first on the line-control card. 

verb-num 

indicates the position of the verb on 
the specified statement before whose 
execution a dynamic dump is given. 
When "verb-num" is not specified, 1 is 
assumed; when specified, "verb-num" 
must follow line-num and may not 
exceed 15. 



ON n [,m] [,k] 

is equivalent to the COBOL statement 
ON n AND EVERY m UNTIL k. This option 
limits the requested dynamic dumps to 
specified times. For example, "ON n" 
would result in one dump, given the 
nth time "line-num" is reached during 
execution. "ON n,m" would result in a 
dump the first time at the nth 
execution of "line-num" and thereafter 
at every mth execution until 
end-of-job. 

(HEX) 

( NOHEX ) 

refers to the format of the Data 
Division areas provided in the dynamic 
dump. If HEX is specified, level-01 
items are provided in hexadecimal. 
Items subordinate to level-01 items 
are printed in EBCDIC, if possible. 
Level-77 items are printed both in 
EBCDIC and hexadecimal. If HEX is not 
specified, items subordinate to 
level-01 items and level-77 items are 
provided in EBCDIC. If unprintable, 
hexadecimal notation is provided. 
Note that if "namel" is specified and 
it represents a group item and HEX has 
not been specified, neither the group 
nor the elementary items in the group 
will be provided in hexadecimal. 



namel [THRU name2] 

represents selected areas of the Data 
Division to be dumped. With the THRU 
option, a range of data-names 
appearing consecutively in the Data 
Division is dumped. "namel" and 
"name2" may be qualified but not 
subscripted. If the programmer wishes 
to see a subscripted item, specifying 
the name of the item without the 
subscript results in a dump of of 
every occurrence of that item. 

ALL 

results in a dump of everything that 
would be dumped in the event of an 
abnormal termination. The purpose of 
ALL is to allow the programmer to 
receive a formatted dump at normal 
end-of-job. To do this, the generated 
statement number of the line on which 
a STOP RUN, EXIT PROGRAM, or GOBACK 
statement appears must be specified as 
the "line-niom" parameter. 

OVERALL CONSIDERATIONS 



The end-of-file control card, slash 
asterisk (/*) must end the symbolic debug 
control card data set. If a run unit 
includes one or more programs that have 
been compiled with the SYMDWP option and no 
symbolic dump is required at execution 
time, the input data set must nevertheless 
be provided, although in this case it 
consists only of the end-of-file (/♦) card. 

If no executable output is produced as a 
result of the compilation (NOLINK, NODECK) , 
any symbolic debugging options specified 
are suppressed. 



SAMPLE PROGRAM -- TESTRUN 



Figure 64 is an illustration of a 
program that utilizes the symbolic 
debugging features. In the following 
description of the program and its output, 
letters identifying the text correspond to 
letters in the program listing. 

(a) Because the SYMDMP option is requested 
on the CEL card, the logical unit 
SYS005 must be assigned at compile 
time. 

Qe) The CBL card specifications indicate 
that an alphabetically ordered 
cross-reference dictionary, a flow 
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trace of 10 procedures, and the 
symbolic debug option are being 
requested. 

\c) An alphabetically ordered 

cross-reference dictionary of 
data-names and procedure-names is 
produced by the compiler as a result 
of the SXREF specification on the CBL 
card. 

(d) The file assigned at compile time to 
SYS005 to store SYMDMP information is 
assigned to sys009 at execution time. 



The SYMDMP control cards placed in the 
input stream at execution time are 
printed along with any diagnostics. 

(^ The first card is the 

program- control card where: 



/ -^ ^ fTlTTi OmTJ TTXT 



T-»T) /^r' TJ T\ AA _ X ■ri 



(b) 9 is the logical unit to which 
the SYMDMP file is assigned. 

(c) MT indicates that the SYMDMP 
file is on tape. 

(d) (HEX) indicates the format of 
the abnormal termination dump. 
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The second card is a line-control 
card which requests a (HEX) 
formatted dynamic dump of KOUNT, 
NAME-FIELD, NO-OF-DEPENDENTS, and 
RECORD-NO prior to the first and 
every fourth execution of 
generated card number 71. 



The third card is also a 
line-control card which requests a 
(HEX) formatted dynamic dump of 
WORK-RECORD and B prior to the 
execution of generated card number 
80. 



The type code combinations used to 
identify data-names in abnormal 
termination and dynamic dumps are 
defined. Individual codes are 
illustrated in Table 34. 

The dynamic dumps requested by the 
first line-control card. 

The dynamic dumps requested by the 
second line-control card. 

Program interrupt information is 
provided by the system when a program 
terminates abnormally. 



The statement number information 
indicates the niamber of the verb and 
of the statement being executed at the 
time of the abnormal termination. The 
name of the program containing the 
statement is also provided. 



(r^ Asterisks appearing within the EBCDIC 
representation of the value of a given 
field indicate that the type and the 
actual content of the field conflict. 



Note: When using the SYMDMP option, level 
niombers appear "normalized" in the symbolic 
dump produced. For example, a group of 



data items described as: 



01 RECORDA. 

05 FIELD-A. 

10 FIELD-Al PIC X. 
10 FIELD-A2 PIC X. 



will appear as follows in SYMDMP output: 



01 RECORDA 

02 FIELD-A... 

03 FIELD-Al.. 
03 FIELD-A2.. 






Debugging TESTRUN 



Referring to the statement nxamber 
information (j) provided by the 
symbolic debug option, it is learned 
that the abend occurred during the 
execution of the first verb on card 



© 



© 
© 

© 



A flow trace of the last 10 procedures 
executed is provided because FLOW=10 
was specified on the CBL card. 

Selected areas of the Task Global 
Table are provided as part of the 
abnormal termination dump. 

For each file-name, the generated card 
number, the file type, SYSnnn, the DTF 
status, and the fields of the Pre-DTF 
and DTF in hexadecimal are provided. 

The fields of records associated with 
each FD are provided in the format 
requested on the program- control card. 

The contents of the fields of the 
Working-Storage Section are provided 
in the format requested on the 
program- control card. 

The value associated with each of the 
possible subscripts are provided for 
data items described with an OCCURS 
clause. 



2. Generated card number 80 contains the 
statement COMPUTE E = B + 1. 



Verifying the contents of B at the 
tigie of the abnormal termination 

^) it can be seen that the usage of 
B (numeric packed) conflicts with the 
value contained in the data area 
reserved for E (numeric display) . 



4. The abnormal termination occurred 

while trying to perform an addition on 
a display item. 



More complex errors may require the use 
of dynamic dumps to isolate the problem 
area. Line-control cards are included in 
TESTRUN merely to illustrate how they are 
used and the output they produce. 



Symbolic Debugging Features 233 



Table 34. Individual Type Codes Used in 
SYMDMP Output 



j Code j Meaning 
j. -(. 





A 


Alphabetic 






B 


Binary 






D 


Display 






E 


Edited 






* 


Subscripted Item 






F 


Floating Point 






N 


Numeric 






P 


Packed Decimal 






S 


Signed 






OT 


Overpunch Sign Trailing 






OL 


Overpunch Sign Leading 






SL 


Separate Sign Leading 






ST 


Separate Sign Trailing 




L 








J 
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// JOB DEBUGL 

// OPTION NODECK, LINK, LIST, LISTX.SYM, ERRS 

// ASSGN SYS005,X'I*83*^ 

// EXEC FCOBOL 




1 IBM DOS VS COBOL 



^^ 



REL 1.0 



PP NO. 5746-CBi 



07.52.05 10/02/73 



CBI SXREF , FLCW=10 , SYKDMP , QUOTE , SEQ 

COOOl 000010 IDENTIFICATION DIVISION. 

CC002 000020 PROGRAK-ID. TESTRUN. 

CC003 000030 AUTHOR. PROGRaKmER NAME. 

cocoa INSTALLATION. NEW YORK DEVELOPMENT CENTER. 

C0005 DATE-WRITTEN. SEPTEMBER 26,1973. 

C0C06 DATE-COKPILED. 10/02/73 

00007 REMARKS. THIS PROGRAM HAS BEEN WRITTEN AS A SAMPLE PROGRAM FOR 

G0008 COBOL USERS. IT CREATES AN OUTPUT FILE AND READS IT BACK 

CCC09 AS INPUT. 

COOIO 000100 

00011 000110 ENVIRONMENT DIVISION. 

C0012 000120 CONFIGURATION SECTION. 

C0013 000130 SOURCE-COMPUTER. IBM-360-H50. 

00014 OOOlitO OBJECT- COMPUTER. IBM-370. 

C0015 000150 INPUT-OUTPUT SECTION. 

C0016 000160 FILE-CONTROL. 

00017 000170 SELECT FILE-1 ASSIGN TO SYS008-UT-2400-S. 

C0018 000180 SELECT FILE-2 ASSIGN TO SYS008-UT-2t00-S. 

C0019 000190 

C0C20 000200 DATA DIVISION. 

C0021 000210 FILE SECTION. 

C0022 000220 FD FILE-1 

C0023 000230 LABEL RECORDS ARE OMITTED 

C0024 000210 BLOCK CONTAINS 5 RECORDS 

C0025 000250 RECORDING MODE IS F 

C0026 000255 RECORD CONTAINS 20 CHARACTERS 

00027 000260 DATA RECORD IS RECORD-1. 

C0028 000270 01 RECORD-1. 

00029 05 FIELD-A PIC X(20). 

C0030 000290 FD FILE-2 

C0031 000300 LABEL RECORDS ARE OMITTED 

C0032 000310 BLOCK CONTAINS 5 RECORDS 

€0033 000320 RECORD CONTAINS 20 CHARACTERS 

C0034 000330 RECORDING MODE IS F 

00035 000340 DATA RECORD IS RECORD-2. 

C0036 000350 01 RECORD-2. 

00037 05 FIELD-A PIC X(20). 




Figure 64. Using the Symbolic Debugging Features to Debug the Program TESTRDN (Part 1 
12) 



of 



Symbolic Debugging Features 235 



IBM DOS VS COBOL 



RZIL 1 . C 



U / . 52 . U3 



C0038 
C0C39 
00040 
00041 
0OC42 
CC043 
C0044 
C0045 
C0046 
00047 
C0048 
00049 
00050 
00051 
C0052 



000370 
000380 



000420 



000450 
000460 
000470 
000480 
000490 

000510 



WORKING-STORAGE SECTION. 
01 FILLER. 

02 KODNT FIC S99 COMP SYNC. 

02 ALPHABET PIC X(26) VALUE "ABCDEFGHIJKLMNOPQRSTUVWXYZ" . 

02 ALPHA REDEFINES ALPHABET PIC X OCCUKS 26 TIKES. 

02 NUMBR PIC S99 COMP SYNC. 

02 DEPENDENTS PIC X{26) VALUE "01234012340123401234012340" 

02 DEPEND REDEFINES DEPENDENTS PIC X OCCURS 26 TIMES. 
01 VgOFK-RECORD . 

05 NAME-FIELD PIC X. 

05 FILLER PIC X. 

05 RECORD- NO PIC 9999. 

05 FILLER PIC X VALUE IS SPACE. 

05 LOCATION PIC AAA VALUE IS "NYC". 

05 FILLER PIC X VALUE IS SPACE. 



C0053 000520 05 NO-OF-DEPENDENTS PIC XX. 

CC054 05 FILLER PIC X(7) VALUE IS SPACES. 

C0055 01 RECCRDA. 

C0056 02 A PICTURE S9(4) VALUE 1234. 

00057 02 E REDEFINES A PICTURE S9(7) COMPUTATIONAL- 3. 

C0058 000550 PROCEDURE DIVISION. 

C0059 BEGIN. 

00060 NOTE THAT THE FOLLOWING OPENS THE OUTPUT FILE 

C0061 TO BE CREATED AND INITIALIZES THE COUNTERS. 

CO 06 2 STEP-1. OPEN OUTPUT FILE-1. MOVE ZERO TO KOUNT, NUMBR. 

CO 063 NOTE THAT THE FOLLOWING CREATES INTERNALLY THE 

CO 06 4 RECORDS TO BE CONTAINED IN THE FILE, WRITES THEM 

C0065 ON TAPE, AND DISPLAYS THEN ON THE CONSOLE. 

CO 06 6 STEP- 2. 'ADD 1 TO KOUNT, NUMBR. MOVE ALPHA (KOUNT) TC 

C0067 NAME-FIELD. 

C0068 MOVE DEPEND (KOUNT) TO NC-OF-DEPENDENTS. 

00069 000660 MOVE NUMER TO RECORD-NO. 

C0070 STEP-3. DISPLAY WORK-RECORD UPON CONSOLE. 

00071 WRITE RECORD-1 FROM WORK-RECORD. 

C0072 STEP-4. PERFORM STEP-2 THRU STEP-3 

C0073 UNTIL KOUNT IS EQUAL TO 26. 

€0074 NOTE THAT THE FOLLOWING CLOSES THE OUTPUT FILE 

CO 07 5 AND REOPENS IT AS INPUT. 

00076 000720 STEP-5. CLOSE FILE-1. OPEN INPUT FILE-2. 

C0077 NOTE THAT THE FOLLOWING READS BACK THE FILE 

00078 AND SINGLES OUT EMPLOYEES WITH NO DEPENDENTS. 

C0079 STEP-6. READ FILE-2 RECORD INTO WORK-RECORD AT END GO TO STEP- 

C0080 COMPUTE B = B + 1. 

CO 081 STEP-7. IF NO-OF-DEPENDENTS IS EQUAL TO "0" MOVE "Z" TO 

CO 08 2 NO-OF-DEPENDENTS. EXHIBIT NAKED WORK-RECORD. 

00083 GO TO STEP-6. 

00084 000780 STEP-8. CLOSE FILE-2. 
C0085 000790 STOP RUN. 



Figure 64. Using the Symbolic Debugging Features to Debug the Program TESTRUN 
{Part 2 of 12) 
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I^L 1.0 



PP NO. 5746-CBl 



07.52.05 10/02/73 



INTRNL NAME 


LVL 


SOURCE NAME 


DNM=1-1U8 


FD 


FILE-1 


DNM=1-179 


01 


RECORD- 1 


DNM=l-200 


02 


FIELE-A 


DNM= 1-217 


FD 


FILE- 2 


DNM=l-248 


01 


RECORD- 2 


DNM=l-269 


02 


FIELE-A 


DNM=l-289 


01 


FILLER 


DNM=l-308 


02 


KOUNT 


DNM=l-323 


02 


ALPHABET 


DNM=1-341 


02 


ALPHA 


DNM=l-359 


02 


NUMBR 


DNiyS=l-37U 


02 


DEPENDENTS 


DNM=l-394 


02 


DEPEND 


DNK=1-410 


01 


WORK-RECORD 


DNM=1-1I3'4 


02 


NAME-FIELD 


DNM=l-454 


02 


FILLER 


DNM=l-473 


02 


RECORD-NO 


DNM=l-492 


02 


FILLER 


DN»=2-00C 


02 


LOCATION 


DNM=2-018 


02 


FILLER 


DNM=2-037 


02 


NO-OF-DEPENDENTS 


DNM=2-063 


02 


FILLER 


DNM=2-082 


01 


RECORDA 


DNM=2-102 


02 


A 


DNM=2-113 


02 


B 



BASE 


DISPL 


INTRNL NAME 


DEFINITION 


USAGE 


DTF=01 




DNM=1-148 






DTFMT 


BL=1 


000 


DNM=1-179 


DS 


0CL20 


GROUP 


BL=1 


000 


DNM=l-200 


DS 


20C 


DISP 


DTF=02 




DNM=1-217 






DTFKT 


BL=2 


000 


DNM=l-248 


DS 


0CL20 


GROUP 


BL=2 


000 


DNM=l-269 


DS 


20C 


DISP 


BL=3 


000 


DNM=l-289 


DS 


0CL56 


GROUP 


BL=3 


000 


DNN=l-308 


DS 


IH 


COKP 


BL=3 


002 


DNM= 1-323 


DS 


2bC 


DISP 


BL=3 


002 


DNM=1-341 


DS 


IC 


DISP 


BL=3 


OIC 


DNM=l-359 


DS 


IH 


CCMP 


BL=3 


OlE 


DNM=l-374 


DS 


26C 


DISP 


BL=3 


OlE 


DNM=l-394 


DS 


IC 


DISP 


BL=3 


038 


DNM=1-410 


DS 


0CL20 


GROUP 


BL=3 


038 


DNM=l-434 


DS 


ic 


DISP 


BL=3 


039 


DNM=l-454 


DS 


IC 


DISP 


BL=3 


03A 


DNM=l-473 


DS 


4C 


DISP-NM 


BL=3 


03E 


DNM=l-492 


DS 


IC 


DISP 


BL=3 


03F 


DNM=2-000 


DS 


3C 


DISP 


BL=3 


042 


DNM=2-018 


DS 


IC 


DISP 


BL=3 


043 


DNM=2-037 


DS 


2C 


DISP 


BL=3 


045 


DNM=2-063 


DS 


7C 


DISP 


BL=3 


050 


DNM=2-082 


DS 


0CL4 


GROUP 


BL=3 


050 


DNM=2-102 


DS 


4C 


DISP-Nhj 


BL=3 


050 


DNM=2-113 


DS 


4P 


COMP-3 



C M 
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MEMORY MAP 



TGT 



00400 



SAVE AREA 

SWITCH 

TALLY 

SORT SAVE 

ENTRY- SAVE 

SORT CORE SIZE 

NSTD-REELS 

SORT RET 

WORKING CELLS 

SORT FILE SIZE 

SORT MODE SIZE 

PGT-VN TBL 

TGT-VN TBL 

SORTAB ADDRESS 

LENGTH OF VN TEL 

LNGTH OF SORTAB 

PGM ID 

A(INITl) 

UPSI SWITCHES 

DEBUG TABLE PTH 

CURRENT PRIORITY 

TA LENGTH 

PROCEDURE BLOCKl PTR 

UNUSED 

RESERVED 

VSAM SAVE AREA ADDRESS 

UNUSED 

RESERVED 

OVERFLOW CELLS 

BL CELLS 

DTFADR CELLS 

FIB CELLS 

TEMP STORAGE 

TEMP STORAGE- 2 

TEMP STORAGE- 3 

TEMP STORAGE -a 

BLL CELLS 

VLC CELLS 

SBL CELLS 

INDEX CELLS 

SUBADR CELLS 

ONCTL CELLS 

PFMCTL CELLS 

PFMSAV CELLS 

VN CELLS 

SAVE AREA =2 

XSASW CELLS 

XSA CELLS 

PARAM CELLS 

RPTSAV AREA 

CHECKPT CTR 

lOPTR CELLS 

DEBUG TABLE 



00400 
00448 
0044C 
00450 
00454 
00458 
0045C 
0045E 
00460 
00590 
00594 
00598 
0059C 
005A0 
005A4 
C05A6 
005A8 
005B0 
005E4 
005EC 
005C0 
005C1 
005C4 
005C8 
005CC 
005D0 
005D4 
005DC 
005F4 
005F4 
00600 
00608 
00608 
00610 
00610 
00610 
00610 
00614 
00614 
00614 
00614 
0061C 
0061C 
0061C 
00620 
00624 
00624 
00624 
00624 
00628 
00628 
00628 
00628 
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REL 1.0 



PP NO. 5746-CBl 



07.5^.05 xu/ui/ 



LITERAL PCCL (HEX) 



CC690 (LIT+0) 
CC6A8 (LIT+24) 



00000001 
5BC2C6C3 



001A1C5B 
B4EUD300 



5BC2C6D7 C5D5405B 
COOOCOOO 



5BC2C3D3 D6E2C55E 



DISPLAY LITERALS (BCD) 
006Bli (LTL+36) ' WCRK-RECORE ' 



PGT 



DEBUG LINKAGE AREA 


00638 


OVERFLOW CELLS 


006U0 


VIRTUAL CELLS 


00640 


PROCEDURE NAME CELLS 


00664 


GENERATED NAKE CELLS 


G0&74 


SUBDTF ADDRESS CELLS 


00688 


VNI CELLS 


00688 


LITERALS 


00690 


DISPLAY LITERALS 


006E4 


PROCEDURE BLOCK CELLS 


006C0 



REGISTER ASSIGNMENT 




REG 6 
REG 7 
REG 8 



BL =3 
BL =1 
BL =2 



WORKING-STORAGE STARTS AT LOCATION 00100 FOR A LENGTH OF 00058. 


59 



0006C0 








0006C0 


58 FO 


C 


018 


000604 


05 EF 






0006C6 


58 FO 


C 


OIC 


0006CA 


05 IF 






0006CC 


003B 






0006CE 


58 FO 


c 


018 


0006D2 


05 EF 






0006D4 


58 FO 


c 


OIC 


0006D8 


05 IF 






0006DA 


003E 






0006DC 


58 FO 


c 


018 


0006E0 


05 EF 






0006E2 


58 20 


D 


1F4 


0006E6 


41 10 


c 


05F 


0006EA 


58 00 


D 


200 


0006EE 


18 40 






0006F0 


07 00 






0006F2 


05 FO 






0006F4 


50 00 


F 


008 



EQU 


* 




L 


15,018(0,12) 


V(ILBEEBG4) 


BALR 


14,15 




L 


15.010(0,12) 


V(ILEEFLWl) 


BALR 


1,15 




DC 


X'003E' 




L 


15,018(0,12) 


V(ILEDDBG4) 


BALR 


14,15 




L 


15,01C(0,12) 


V(ILEEFLWl) 


EALR 


1,15 




DC 


X'003E' 




L 


15,018(0,12) 


V(ILEEEBG4) 


BALR 


14,15 




L 


2,1F4(0,13) 


EL =1 


LA 


1,05F(0,12) 


LIT+7 


L 


0,200(0.13) 


DTF=1 


LR 


4,0 




BCR 


0,0 




BALR 


15, C 




ST 


0,008(0,15) 





♦STATISTICS* 
♦STATISTICS* 
♦OPTIONS IN EFFECT* 
♦CFTICNS IN EFFECT* 
♦OPTIONS IN EFFECT* 
*CFTICNS IN EFFECT* 



SOURCE RECORDS = 85 

PARTITION SIZE = 655176 

PMAP RELOC ADR = NONE 

LISTX QUOTE 

NOCLIST FLAGW 

NOSTATE TRUNC 



DATA ITEMS = 

LINE COUNT = 

SPACING 

SYM NOCATALR 

ZWB NOSUPMAP 

SEQ SYMDMP 



25 


NO OF 


VERBS = 


29 




56 


BUFFER 


: SIZE = . 


512 




1 


FLOW 


= 


10 






LIST 


LINK 


NCSTXIT 


NCLIB 




NOXREF 


ERRS 


SXREF 


NCOPT 




NODECK 


NOVERB 


NOSYNTA_X 


NCLVL 
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RECORD- 2 

RECORDA 

WORK-RECORD 

BEGIN 

STEP-1 

STEP-2 

STEP-3 

STEP-4 

STEP-5 

STEP-6 

STEP-7 

STEP-8 



DEFN 


REFERENCE 




000056 








000042 


000066 






oooom 








000057 


000080 






000045 


000068 






000044 








000029 








000037 








000017 


000062 


000071 


000076 


000018 


000076 


000079 


000084 


000040 


000062 


000066 


000068 


000051 








000047 


000066 






000053 


000068 


000061 




000043 


000062 


000066 


000069 


000049 


000069 






000028 


000071 






000036 


000079 






000055 








000046 


000070 


000071 


000079 


000059 








000062 








000066 


000072 






000070 


000072 






000072 








000076 








000079 


000083 






000081 








000084 


000079 







ERROR MESSAGE 



00056 ILA2190I-W 
00066 ILA5011I-W 
00066 ILA5011I-W 



PICTURE CLAUSE IS SIGNED, VALUE CLAUSE UNSIGNED. 
HIGH ORDER TRUNCATION MIGHT OCCUR. 
HIGH ORDER TRUNCATION MIGHT OCCUR. 



ASSUMED POSITIVE. 



// EXEC LNKEDT 



JOE DEBUGL 



DOS LINKAGE EDITOR DIAGNOSTIC OF liiPUT 



ACTION 

LIST 

LIST 

LIST 

LIST 

LIST 

LIST 

LIST 

LIST 

LIST 

LIST 

LIST 

LIST 



TAKEN MAP REL 
AUTOLINK IJFFEZZN 
AUTOLINK ILBDADRO 
AUTOLINK ILBDDBGO 
INCLUDE IJJCPDV 
AUTOLINK ILBDDSPO 
AUTOLINK ILEDDSSO 

INCLUDE IJJCPDV 
AUTOLINK ILBDFLWO 



AUTOLINK 
AUTOLINK 

AUTOLINK 
ENTRY 



ILEDIMLO 
ILBDMNSO 
ILBDSAEO 



Figure 6^^. Using the Symbolic Debugging Features to Debug the Program TESTRUN 
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IBM DOS VS COBOL 



REL 1.0 



PP NO. 5746-CBl 



07.52.05 10/02/73 



PHASE XFR-AD LOCORE HICCRE DSK-AD 
PHASE*** 07D878 07E878 0803EF 05F OF U CSECT 



* UNREFERENCED SYMBOLS 



003 UNRESOLVED ADDRESS CONSTANTS 



ESD TYPE 


LABEL 


LOADED 


REL-FR 


CSECT 


TESIRUN 


07D878 


07D878 RELOCATABLE 


CSECT 


IJFFEZZN 


07E368 


07j:.368 


* ENTRY 


IJFFZZZN 


07E368 




* ENTRY 


IJFFEZZ2. 


07E368 




* ENTRY 


IJFFZZZZ 


07E368 




CSECT 


ILBDSAEO 


080268 


080268 


ENTRY 


ILBDSAEl 


0802B0 




CSECT 


ILEDMNSO 


080260 


08C260 


CSECT 


ILBDDBGO 


07EAC0 


07EACG 


ENTRY 


ILBDDEG5 


07EFA2 




ENTRY 


ILBDDEGU 


07F014 




ENTRY 


ILBDDBG7 


07F038 




ENTRY 


ILBDDBG2 


C7ED8A 




* ENTRY 


ILBDDEGl 


07EC1C 




* ENTRY 


ILBDDBG3 


07F00A 




* ENTRY 


ILBDDBG6 


07F024 




ENTRY 


STXITPSW 


07F0DO 




* ENTRY 


SORTEP 


07F270 




CSECT 


ILBDFLWO 


07FD70 


07FD70 


ENTRY 


ILBDFLWl 


07FE30 




ENTRY 


ILBDFLW2 


07FF0C 




CSECT 


ILBDIMLO 


080208 


080208 


CSECT 


ILBDADRO 


07E718 


07E718 


* ENTRY 


ILBDADRl 


07E724 




CSECT 


ILBDDSPO 


07F518 


07F518 


ENTRY 


ILBDDSPl 


07F918 




CSECT 


IJJCPDV 


07E878 


07E878 


ENTRY 


IJJCPDVl 


07E878 




* ENTRY 


IJJCPDV 2 


07E878 




CSECT 


ILBDDSSO 


07FA48 


C7FA48 


ENTRY 


ILBDDSSl 


07FCA8 




ENTRY 


ILBDDSS2 


07FCA0 




ENTRY 


ILBDDES3 


07FD60 




ENTRY 


ILBDDSS4 


07FA6E 




ENTRY 


ILBDDSS5 


07FB1A 




ENTRY 


ILBDDSS6 


07FB7A 




ENTRY 


ILBDDSS7 


07FBa4 




ENTRY 


ILBDDSS8 


07FA9E 




WXTRN 


ILBDSTNO 






WXTRN 


ILBDSRTO 






ViXTRN 


ILBDTEF3 







« 



// ASSGN SYS008,X'482' 
// ASSGN SYS009,X'483' 
// EXEC 



^ 



Figure 54. Using the Symbolic Debugging Features to Debug the Program TESTRON 
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IBM DOS VS COBOL 



ff NU. 5/4b-t;Bl 



J-U/ Ui/ / o 



SYKDKP CONTROL CARES 



^T) TLSTBUN,009,MT, (HEX) i 

(T) 71,ON l,t, (HEX) ,KOUNT,NAiyiE-FIELD,N0-CF-EEPENDENTS, RECORD-NO ) {ij 

^3^ 80, (HEX), WORK-RECORD, E 



NO ERRORS FOUND IN CONTROL CARDS 



© 



® 



CODE 

A 

AN 

ANE 

D 

DE 

F 

FD 

NB 

NE-S 

ND 

ND-OL 

ND-OT 

ND-SL 

ND-ST 

NE 

NP 

NP-S 



TESTRUN AT CARD 000071 
LCC CARD LV NAME 

07E978 OOOOtO 02 KOUNT 

07B9BO 000047 02 NAME-FIELE 
07E9EE 000053 02 NO-OF-DEPENDENTS 
07D9B2 000049 02 RECGRD-NO 



TYPE CODES USED IN SYKDMP OUTPUT 

J1EANING 

ALPHABETIC 

ALFHANUKEi<IC 

ALPHANUMERIC EDITED 

DISPLAY (STERJ-ING NONREFORT) 

DISPLAY EEITED (STERLING REPORT) 

FLOATING POINT (COMP-l/COKP-2) 

FLOATING POINT DISPLAY (EXTERNAL FLOATING POINT) 

NUMERIC BINARY UNSIGNED (COMP) 

NUMERIC BINARY SIGNED 

NUMERIC DISPLAY UNSIGNED (EXTERNAL DECIMAL) 

NUMERIC DISPLAY OVERPUNCH SIGN LEADING 

NUMERIC DISPLAY OVERPUNCH SIGN TRAILING 

NUMERIC DISPLAY SEPARATE SIGN LEADING 

NUMERIC DISPLAY SEPARATE SIGN TRAILING 

NUMERIC EDITED 

NUMERIC PACKED DECIMAL UNSIGNED (CCMP-3) 

NUMERIC PACKED DECIMAL SIGNED 

SUBSCRIPTED 



(HEX) 



TYPE 


VALU: 


NB-S 


+ 01 




0001 


AN 


A 


AN 





ND 


0001 



TESTRUN AT CARD 000071 
LCC CARD LV NAME 

07E978 000040 02 KOUNT 

07E9B0 000047 02 NAME-FIELD 
07E9EE 000053 02 NO-OF-DEPENDENTS 
07E9B2 00004 9 02 RECCRD-NO 



(HEX) 



TYPE 


VALU: 


NB-S 


+ 05 




0005 


AN 


E 


AN 


4 


NB 


0005 



TESTRUN AT CARD 000071 
LCC CARD LV NAME 

07D978 000040 02 KOUNT 

07B9B0 000047 02 NAME-FIELD 
07E9EE 000053 02 NO-OF-DEPENDENTS 
07D9B2 000049 02 RECORD-NO 



(HEX) 



TYPE 


VALU: 


NB-S 


+ 09 




0009 


AN 


I 


AN 


3 


ND 


QM9 



Fxgure 64. Using the Symbolic Debugging Features to Debug the Program TESTRUN 
(Part 8 of 12) 



242 



IBM DOS VS COBOL 



EEL 1.0 



PP NO. 5746-CBl 



07.52,05 10/02/73 



TESTEUK AT CABD 000071 
LCC CARD LV NAME 

07D978 000040 02 KOUNT 

07D9BO 0000U7 02 NAME-FIELB 
07E9EE 000053 02 NO-pF-DEPENDENTS 
07E9E2 000049 02 RECCRD-NO 



(HEX) 



TYPE 


VALUE 


NB-S 


+ 13 




OOOD 


AN 


M 


AN 


2 


ND 


0013 



TESTRUio AT CAPD 000071 
LCC CARD LV NAME 

07D978 000040 02 KOUNT 

07E9B0 000047 02 NAME-FIELB 
07D9EE 000053 02 NO-CF-DEPENDENTS 
07B9B2 000049 02 RECCRD-NO 



(HEX) 



TYPE 


VALU: 


NB-S 


+ 17 




0011 


AN 


Q 


AN 


1 


ND 


0017 




TESTRUN AT CARD 000071 
LCC CARD LV NAME 

07D978 000040 02 KOUNT 

07E9B0 000047 02 NAME-FIELD 
07B9EE 000053 02 NC-CF-DEPENDENTS 
07D9B2 000049 02 RECCRD-NO 



(HEX) 



TYPE 


VALU] 


NB-S 


+ 21 




0015 


AN 


U 


AN 





ND 


0021 



TESTRUN AT CARD 000071 
ICC CARD LV NAME 



07E978 000040 02 KOUNT 



07E9E0 000047 02 NAME-FIELD 



07E9BE 00005 3 02 NC-OF-DEPENDENTS 



07E9E2 000049 02 RECORD-NO 







TESTRUN AT CARD 00008 
LCC CARD LV NAME 





000046 


01 


WORK-RECORD 


07E9B0 








07E9E0 


000047 


02 


NAME-FIELD 


07E9B1 


000048 


02 


FILLER 


07E9E2 


000049 


02 


RECORD-NO 


07E9B6 


000050 


02 


FILLER 


07E9E7 


000051 


02 


LOCATION 


07E9BA 


000052 


02 


FILLER 


07E9EE 


000053 


02 


NO-CF-DEPENDENTS 


07E9BD 


000054 


02 


FILLER 



07E9C8 000057 02 B 



(HEX) 



TYPE 


VALU: 


NB-S 


+ 25 




0019 


AN 


Y 


AN 


4 


ND 


0025 



(HEX) 



C107F0F0 F0F140D5 E8C340F0 40404040 40404040 



AN 


A 


AN 


* 


ND 


0001 


AN 




A 


NYC 


AN 




AN 





AN 




NP-S 


*1*2*3* 




F1F2F3C4 
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IBM DOS VS COBOL 



REL 1.0 



PP NO. 5746-CBl 



07.52.05 10/02/73 



COBOL ABEND DIAGNOSTIC AIDS 



© 



INTERKUPl CODE 7 LAST PSW ADDR BEFORE ABEND D007E1AE 

PRCGRAK TESTRUH 

LAST CARD NUMBER/VERB NUMBER EXECUTED — CARD NUKEER 00008 0/VERB NUMBER 01. 



FLOW TRACE 
TESTRUN 000066 000070 000066 000070 000066 000070 000066 000070 000076 000079 



© 
® 



DATA DIVISION DUMP OF TESTRUN 



© 



TASK GLOBAL TABLE 



SAVE AREA 


07DC78 


0000F233 


1B009101 


00080168 


8007E18E 




07DC98 


OOOOOOIA 


0007EA60 


5007E29A 


0007D978 




07DCB8 


1»007E1AE 


0007DEB0 






SWITCH 


07DCC0 


3C10004B 








TALLY 


07DCCa 


00000000 








SORT-SAVE 


07DCC8 


00000000 








ENTRY-SAVE 


07DCCC 


0007DF38 








SCRT -CORE-SIZE 


07DCD0 


00000000 








NSTD-REELS 


07DCD4 


0000 








SORT-RETURN 


07ECE6 


0000 








WORKING CELLS 


07DCD8 


0007DA60 


0007DB40 


OOOOOOIA 


0007DA60 




07DCF8 


F0F2F640 


D5E8C340 


F0404040 


40404040 




07DD18 


HOtlOUOHO 


40404040 


40404040 


40404040 




07DD38 


— SAME— 










07DD58 


40404040 


40404040 


40404040 


40404040 




07DD78 


OOOOOOIA 


01000000 


0007ii070 


0007F518 




07DD98 


0007D9AF 


5007E29A 


0007D978 


0007DAD8 




07DDB8 


0007DEB0 


55E0F088 


4780F030 


18FE05EF 




07DDD8 


0007FA4 8 


0007E084 


0007F518 


4A50F060 




07DDF8 


00000000 


00000000 


07070607 


07070707 


SORT-FILE-SIZE 


07DE08 


00000000 








SCRT-MODE-SIZE 


07DE0C 


00000000 








FGT-VN TBL 


07DE10 


E2C1D4D7 








TGT-VN TBL 


07DE14 


D3C54040 








SORTAB ADDR 


07DE18 


0007D878 








VN TBL LENGTH 


07DE1C 


0000 








SORTAB LENGTH 


07DE1E 


0000 








FRCGRAM-ID 


07DE20 


TESTRUN 








A(INITl) 


07DE28 


0007D878 








UPSI-SWITCHES 


07DE2C 


C9D3C2C4 


D6E2E8F0 






TGT-DBG TABLE 


07DE34 


00000228 








CURRENT PRIORITY 


07DE38 


00 








TRANSIENT AREA LENGTH 


07DE39 


689120 








FRGCEDURE-BLCCK 


07DE3C 


E0004780 








UNUSED 


07DEttO 


F0325810 








RESERVED 


07DEija 


F0789101 








VSAM SAVE AREA 


07DEa8 


10004710 








UNUSED 


07DE'*C 


F0329601 


00000000 






RESERVED 


07DE54 


00000000 


F0549110 


000002E0 


00000100 


OVERFLOW CEILS 


(NONE) 










EL CELLS 


07DE6C 


0007DAEC 


0007EEA8 


0007D978 




ETFADR CELLS 


07DE78 


0007D9E8 


0007DA60 






FIB CELLS 


(NONE) 










TEMP STORAGE 


07DE80 


00000000 


0000026C 






ELL CELLS 


07DE88 


00000000 








VIC CELLS 


(NONE) 










SEL CELLS 


(NONE) 










INDEX CELLS 


(NONE) 










OTHER (SEE MEMORY MAP) 


07DE8C 
07DEAC 


0007D993 
000006F8 


0007E9AF 


0007EOAC 


0007E0AC 



0007E1A8 4007E1AA 0007DA60 0007DBA8 
0007DAEC 0007DBA8 0007E264 0007D878 



5007E29A F16E9025 F21290BC 40E907F0 
40404040 40404040 40404040 40404040 
40404040 40404040 40404040 40404040 

40404040 40400000 OOOOOOOC 0007E082 
0007D9AF 0007E084 OOOOOOIA OOOOOOIA 
0007DBA8 0007E264 0007D878 4007E08A 
18F498E4 F0684B00 00024620 0007E082 
4A20F060 183047F0 F036D200 50002000 



000002A8 D4C5E3C8 



D7C5D540 OA00OA68 000009D2 5C29F0C8 
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IBM DOS VS COBOL 



REL 1.0 PP NO. 5746-CBl 

DATA DIVISION DUMP OF TESTRUN 



07.52.05 10/02/73 



LCC 


CARD 


LV 


NAME 






000017 


FD 


FILE-1 (M) 




07E9D0 








PRE-DTF 


07E9E8 








DTFMT 


07DA08 










07EA28 










07EAit8 












000028 


01 


RECORD-1 (n) 




07DAEC 








07EAEC 


000029 


02 


FIELD-A 






000018 


FD 


FILE-2 (S) 




07DAit8 








PRE-DTF 


07EA60 








DTFMT 


07DA80 










07EAA0 










07DAC0 












000036 


01 


RECORD- 2 (n) 




07EBA8 








07EBA8 


000037 


02 


FIELD-A 






000039 


01 


FILLER (f) 




07E978 








07D990 










07E9A8 










07D978 


000040 


02 


KCUNT 




07E97A 


OOOOUl 


02 


ALPHABET 






000042 


02 


ALPHA 




07B97A 






(^ (SUBl) 




07E97E 






2 




07E97C 






3 




07E97D 






4 




07D97E 






5 




07E97F 






6 




07E980 






7 




07E981 






8 




07D982 






9 




07E983 






10 




07D98a 






11 




07E985 






12 




07D986 






13 




07E987 






14 




07D988 






15 




07E989 






16 




07E98A 






17 





TYPE VALUE 

STANDARD SEQUENTIAL ASSIGNED TC SYS008, CLOStB 



01010014 00000000 00000000 00000000 
00009200 OC000108 0007DA20 0C07DA28 
00000000 00000000 OOOOCOOO 86BCF018 
0007DB40 0007DB40 00000014 0007DBA3 
01010014 00000000 00000000 00000000 



6COOOOO0 00000000 

0007E368 1160E2E8 E2F0FCF8 40400162 

41E0E0C1 58201044 0107DAD8 20000064 

00640063 00000000 00000000 400802b8 

6C000000 00000000 00008200 OC000108 



(HEX) 



D807F0F0 F1F740D5 E8C340F1 
Q+0017 NYC 1 



40404040 40404040 



STANDARD SEQUiiNTIAL ASSIGNED TO SYS008, OPEN INPUT 



01010014 00000000 00000000 00000000 

00008200 OC000108 0007BA98 0007DAA0 

10000000 2407E1A2 00000001 86BCF018 

0007DBA8 0007DBA8 00000014 0007DC0B 



6C000000 00000000 

0007E368 11E8E2E8 E2F0F0F8 40400272 
41E0E001 58201044 0207BC10 00000064 
00640063 00000000 000802B0 00080268 



00000000 00000000 00000000 00000000 00000000 00000000 E907F0F0 F2F640D5 



(HEX) 



(HEX) 



NB-S 
AN 
♦AN 






C107F0F0 F0F140D5 E8C340F0 
A*0001 NYC 



001AC1C2 C3C4C5C6 C7C8C9E1 
E6E7E8E9 OOIAFOFI F2F3F4F0 
F3f4F0Fl F2F3F4F0 
+ 26 
ABCDEFGHIJKLMNOPQRSTUVWXYZ 



40404040 40404040 



D2D3D4D5 D6D7D8D9 t2E3E4E5 
F1F2F3F4 F0F1F2F3 F4fOFlF2 
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IBM DOS v*S COBOL 



REL 1.0 



PP NO. 5746-CBl 



07.52.05 10/02/73 



DATA CIVISION DUKP OF TESTRUN 



LCC 


CARD 


LV 


NAME 




07D98B 








18 


07E98C 








19 


07D98D 








20 


07E98E 








21 


07D98F 








22 


07E990 








23 


07D991 








24 


07E992 








25 


07D993 








26 


07E994 


000043 


02 


NUMER 




07D996 


000041* 


02 


DEPENDENTS 




0000H5 


02 


DEPEND 




07E996 






® 


(SUBl) 

1 


07B997 








2 


07E998 








3 


07E999 








4 


07E99A 








5 


07E99B 








6 


07E99C 








7 


07E99B 








8 


07E99£ 








9 


07E99f 








10 


07E9AC 








11 


07B9A1 








12 


07E9A2 








13 


07D9A3 








14 


07E9A4 








15 


07E9A5 








16 


07E9A6 








17 


07E9A7 








18 


07E9A8 








19 


07D9A9 








20 


07E9AA 








21 


07D9AE 








22 


07E9AC 








23 


07E9AD 








24 


07E9AE 








25 


07E9AF 








26 




000046 


01 


WORK-RECORD (p) 


07B9B0 








^-^ 


07E9B0 


000047 


02 


NAME-FIELD 


07D9B1 


000048 


02 


FILLER 




07E9B2 


000049 


02 


RECORD- 


-NO 


07E9B6 


000050 


02 


FILLER 




07E9E7 


000051 


02 


LOCATION 


07E9BA 


000052 


02 


FILLER 




07E9EE 


000053 


02 


NO-OF-DEPENDENTS 



NB-S 
AN 
♦AN 



(HEX) 



AN 

AN 

ND 

AN 

A 

AN 

AN 



R 
S 
1 
U 

V 

w 

X 
Y 

z 

+ 26 
01234012340123401234012340 



C107F0F0 F0F140D5 E8C340F0 
A 

* 
0001 

NYC 





40404040 40404040 



DATA DIVISION DUMP OF TESTRUN 



LCC CARD LV NAME 

07E9BD 000054 02 FILLER 

000055 01 RECORDA 
07E9C8 

07D9C8 000056 02 A 

07D9C8 000057 02 B 



® 



TYPE VALUE 
AN 



(HEX) F1F2F3C4 

^.^ ND-OT +1234 
r^V NP-S *1*2*3* 



END OF COBOL DIAGNOSTIC AIDS 
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PROGRAiyi CHECKOUT 



A programmer using the DOS/VS COBOL 
Compiler and Library has several methods 
available to him for testing and debugging 
his programs. Use of the symbolic 
debugging features is the easiest and most 
efficient method for testing and debugging 
and is described in detail in the chapter 
"Symbolic Debugging Features," Using the 
execution statistics feature is another 
method for testing, debugging and 
optimizing a program, and is described in 
the chapter "Execution Statistics". 

This chapter contains information useful 
for testing and debugging programs run 
without the symbolic debugging features. 
It also contains information on linkage 
editor and execution-time diagnostics as 
well as a description of taking checkpoints 
and restarting programs. 



SYNTAX-CHECKING COMPILATION 



The compiler checks the source text for 
syntax errors and then generates the 
appropriate error messages. With the 
syntax-checking feature, the programmer can 
request a compilation either conditionally, 
with object code produced only if no 
messages or just W- or C-level messages are 
generated, or unconditionally, with no 
object code produced regardless of message 
level. 

Selected test cases run with the 
syntax-checking feature have resulted in a 
compilation- time saving of as much as 70%, 
For a discussion of the syntax-checking 
options, SYNTAX and CSYNTAX, see the 
section "CBL Statement — COBOL Option 
Control Card." 



IDENTIFICATION OF PROGRAM VERSIONS 



One problem a programmer may have during 
checkout is associating a particular 
compilation listing with the object deck 
from that compilation and the output and/or 
dump from a particular run. To aid in 
this, the following facilities can be used: 

1. Specify a DATE-COMPILED paragraph as 
part of the Environment Division. 
This is replaced by the actual date of 
compilation on the source listing 
(OPTION LIST). 



2. The date and time of compilation are 
given in the header line of the 
compilation listing. 

3. The date and time of compilation are 
punched into the object deck and will 
be found beginning at relative 
location X'EC in the dump of the 
object module. 

4. By moving the special register 
WHEN-COMPILED to an output record, the 
user may flag his output to identify 
it with a particular compilation. 
WHEN-COMPILED is described more fully 
in IBM DOS Full American National 
Standard COBOL. 



DEBUG LANGUAGE 



The COBOL debugging language is designed 
to assist the COBOL programmer in producing 
an error-free program in the shortest 
possible time. The following sections 
discuss the use of the debug language and 
other methods of program checkout. 

The three debug language statements are 
TRACE, EXHIBIT, and ON. Any one of these 
statements can be used as often as 
necessary. They can be interspersed 
throughout a CCBOL source program, or they 
can be contained in a packet in the input 
stream to the compiler. 

Program checkout may not be desired 
after testing is completed. A debug packet 
can be removed after testing to eliminate 
the extra object program coding generated 
for the debug statements. 

The output produced by the TRACE and 
EXHIBIT statements is listed on the system 
logical output device (SYSLST) . 

The following discussions describe 
methods of using the debug language. 



FLOW OF CONTROL 



The READY TRACE Statement causes the 




V^ VJlll k-l J. J. ^ J- 



■generated card numbers for each 
section-name and paragraph-name to be 
displayed. These card numbers are listed 
on SYSLST at execution time when control 
passes to these sections and paragraphs. 
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Hence, the output of the READY TRACE 
statement appears as a list of card 
numbers. If VERB is specified, the actual 
paragraph-names and names of the verbs will 
be listed. 



Note ; If an error occurs during 
compilation of an ON statement, the 
diagnostic message may refer to the 
previous statement number. 



To reduce the length of the list and the 
time taken to generate it, a trace can be 
stopped with a RESET TRACE statement. The 
READY TRACE/RESET TRACE combination is 
helpful in examining a particular area of 
the program where the flow of control is 
difficult to determine, e.g., code consists 
of a series of PERFORM statements or nested 
conditional statements. The READY TRACE 
statement can be coded so that the trace 
begins before control passes to that area. 
The RESET TRACE Statement can be coded so 
that the trace stops when the program has 
passed beyond the area. 



Use of the ON statement with the TRACE 
statement allows conditional control of the 
tracing. When the COBOL compiler 
encounters an ON statement, it creates a 
counter which is incremented during 
execution, whenever control passes through 
that ON statement. For example, if an 
error occurs when a specific record is 
processed, the ON statement can be used to 
isolate the problem record. The statement 
should be placed where control passes 
through it only once for each record that 
is read. When the contents of the counter 
equal the number of the record (as 
specified in the ON statement) , a trace can 
be taken on that record. The following 
example shows a method in which the 200th 
record could be selected for a TRACE 
statement. 



DISPLAYING DATA VALUES DURING EXECUTION 



A programmer can display the value of a 
data item during program execution by using 
the EXHIBIT statement. The EXHIBIT 
statement has three options: 

1. EXHIBIT NAMED — Displays the names 
and values of the data-names listed in 
the statement. 

2. EXHIBIT CHANGED -- Displays the value 
of the data-names listed in the 
statement only if the value has 
changed since the last execution of 
the statement. 

3. EXHIBIT CHANGED NAMED — Displays the 
names and the values of the data-names 
only if the values have changed since 
the last execution of the statement. 

Data values can be used to check the 
accuracy of the program. For example, 
using EXHIBIT NAMED, the programmer can 
display specified fields from records, 
compute the calculations himself, and 
compare his calculations with the output 
from his programi. The coding for a payroll 
problem might be: 



Col. 
1 



Area A 



Col. 
1 



Area A 
RD-REC . 



GROSS- PAY- CALC. 

COMPUTE GROSS-PAY = 
RATE- PER- HOUR ♦ (HRSWKD 
+ 1.5 ♦ OVERTIMEHRS). 

NET- PAY- CALC. 



DEBUG 



RD-REC 
PARA-NM-1. 



ON 200 READY TRACE. 
ON 201 RESET TRACE. 



If the TRACE statement were used without 
the ON statement, every record would be 
traced. 

An example of a common program error is 
failing to break a loop or unintentionally 
creating a loop in the program. If many 
iterations of the loop are required before 
it can be determined that a program error 
exists, the ON statement can be used to 
initiate a trace after the expected number 
of iterations has been completed. 



DEBUG NET-PAY-CALC 

SAMPLE- 1. ON 10 AND 

EVERY 10 EXHIBIT NAMED 
RATE- PER- HOUR, HRSWKD, 
OVERTIMEHRS, GROSS-PAY. 

This coding will cause the values of the 
four fields to be listed for every tenth 
data record before net pay calculations are 
made. The output could appear as: 

RATE- PER- HOUR = 4.00 HRSWKD = 4 0.0 

OVERTIMEHRS =0.0 GROSS-PAY = 160.00 

RATE-PER-HOUR = 4.10 HRSWKD = 40.0 

OVERTIMEHRS =1.5 GROSS-PAY = 173.23 
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RATE-PER-HOUR = 3.35 HRSWKD = 40.0 

OVERTIMEHRS = 0.0 GROSS-PAY = 134.00 

Note: Decimal points are included in this 
example for clarity, but actual printouts 
depend on the data description in the 
program. 
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The preceding was an example of checking 
at regular, intervals (every tenth record) . 
A check of any unusual conditions can be 
made by using various combinations of COBOL 
statements in the debug packet. For 
example: 



IF OVERTIMEHRS GREATER THAN 2.0 
EXHIBIT SAMED PAYRCDHRS... 



In connection with the previous example, 
this statement could cause the entire pay 
record to be displayed whenever an unusual 
condition (overtime exceeding two hours) is 
encountered. 



The EXHIBIT statement with the CHANGED 
option also can be used to monitor 
conditions that do not occur at regular 
intervals. The values of data-names are 
listed only if the value has changed since 
the last execution of the statement. For 
example, suppose the program calculates 
postage rates to various cities. The flow 
of the program might be: 



IREAD INPUT I 
I DATA FOR |<- 
I CITY I 



I CALCULATE 
I RATE FOR 
I CITY 



I EXHIBIT I 
I CHANGED I 



LAST 
CITY 




NO 



->B 




YES 



STATE = 01 CITY = 01 RAIL = 10 BUS = 14 TRUCK = 12 AIR = 20 

CITY = 02 

CITY = 03 BUS = 06 AIR = 15 

CITY = 04 RAIL = 30 BUS = 25 TRUCK = 28 AIR = 34 

STATE = 02 CITY = 01 TRUCK = 25 

CITY = 02 TRUCK = 20 AIR = 30 



Figure 65. Sample Output of EXHIBIT Statement With the CHANGED NAHED Option 
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The EXHIBIT statement with the CHANGED 
option in the program might be: 

EXHIBIT CHANGED STATE CITY RATE 

The output from the EXHIBIT statement 
with the CHANGED option could appear as: 



01 


01 


10 




02 


15 




03 






04 


10 


02 


01 






02 


20 




03 


15 




04 




03 


01 


10 



The first column contains the code for a 
state, the second column contains the code 
for a city, and the third column contains 
the code for the postage rate. The value 
of a data-name is listed only if it has 
changed since the previous execution. For 
example, since the postage rate to city 02 
and city 03 in state 01 are the same, the 
rate is not printed for city 03. 



The EXHIBIT statement with the CHANGED 
NAMED option lists the data-name if the 
value has changed. For example, the 
program might calculate the cost of various 
methods of shipping to different cities. 
After the calculations are made, the 
following statement could appear in the 
program : 

EXHIBIT CHANGED NAKED STATE CITY RAIL 
BDS TRUCK AIR 

The output from this statement could appear 
as shown in Figure 65. Note that a 
data-name and its value are listed only if 
the value has changed since the previous 
execution. 



START 



STOP 
RUN 



DEBUG 
PACKET 
FOR A 



I DEBUG 
I PACKET 
I FOR C 



In this program, A creates data, B 
processes it, and C prints it. The debug 
packet for A simulates test data. It is 
first in the program to be executed. In 
the packet, the last statement is GO TO B, 
which permits A to be bypassed. After B is 
executed with the test data, control passes 
to the debug packet for C, which contains a 
GO TO statement that transfers control to 
the end of the program, bypassing C. 



TESTING A PROGRAM SELECTIVELY 



A debug packet allows the programmer to 
select a portion of the program for 
testing. The packet can include test data 
and can specify operations the programmer 
wants to be performed. When the testing is 
completed, the packet can be removed. The 
flow of control can be selectively altered 
by the inclusion of debug packets, as 
illustrated in the following example of 
selective testing of B: 



TESTING CHANGES AND ADDITIONS TO PROGRAMS 



If a program runs correctly, and changes 
or additions might improve its efficiency, 
a debug packet can be used to test changes 
without modifying the original source 
program. 



the 



If the changes to be incorporated are in J 
middle of a paragraph, the entire 
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paragraph with the changes included must be 
written in the debug packet. The last 
statement in the packet should be a GO TO 
statement that transfers control to the 
next procedure to be executed. 

There are usually several ways to 
perform an operation. Alternative methods 
can be tested by putting them in debug 
packets. 

The source program library facility can 
be used for program checkout by placing a 



\iiT'f^cx rvT-rtrri-ai 
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chapter "Librarian Functions") . Changes or 
additions to the program can be tested by 
using the BASIS card and any number of 
INSERT and DELETE cards ► Such changes or 
additions remain in effect only for the 
duration of the run. 

A debug packet can also be used in 
conjunction with the BASIS card to debug a 
program or to test deletions or additions 
to it. The debug packet is inserted in the 
input stream immediately following the 
BASIS card and any INSERT or DELETE cards. 



DUMPS 



2. Hexadecimal address of the instruction 
that caused the interrupt 



Condition code 



Reason for the interrupt (for example, 
data exception) 



The instruction address can be compared 
to the Procedure Division map. The 
contents of LISTX ^^rovide a relative 
address for each statement. The load 
address of the module (which can be 
obtained from the map of virtual storage 
generated by the Linkage Editor) must be 
subtracted from the instruction address to 
obtain the relative instruction address as 
shown in the Procedure Division map. The 
PHAP=nnnnnn CBL option can be used to 
relocate LISTX addresses so that this 
calculation need not be done. If the 
interrupt occurred within the COBOL 
program, the programmer can use the error 
address and LISTX to locate the specific 
statement in the program which caused a 
dump to be taken. Examination of the 
statement and the fields associated with it 
may produce information as to the specific 
nature of the error. 




If a serious error occurs during 
execution of the problem program, the job 
is abnormally terminated; any remaining 
steps are bypassed; and a program phase 
dump is generated. The programmer can use 
the dump for program checkout. (However, 
any pending transfers to an external device 
may not be completed. For example, if a 
READY TRACE statement is in effect when the 
job is abnormally terminated, the last card 
number may not appear on the external 
device.) In cases where a serious error 
occurs in other than the problem program 
(for example, Supervisor), a dump is not 
produced. Note that program phase dximps 
can be suppressed if the NODUMP option 
of the OPTION control statement has been 
specified for the job, or if NODUMP was 
specified at system generation time and 
is not overridden by the DUMP option for 
the current job. 



HOW TO USE A DUMP 



Hhen a job is abnormally terminated due 
to a serious error in the problem program, 
a message is written on SYSLST which 
indicates the: 



1. Type of interrupt (for example, 
program check) 



Figure 66 is a sample dump which was 
caused by a data exception. Invalid data 
(i.e., data which did not correspond to its 
usage) was placed in the numeric field B as 
a result of redefinition. The following 
discussion illustrates the method of 
finding the specific statement in the 
program which caused the dump. Letters 
identifying the text correspond to letters 
in the program listing. 

(a^ The program interrupt occurred at HEX 
LOCATION 07DFDC. This is indicated in 
the SYSLST message printed just before 
the dump. 

The linkage editor map indicates that 
the program was loaded into address 
7D878. This is determined by 
examining the load point of the 
control section TESTRUN. TESTRUN is 
the name assigned to the program 
module by the source coding: 

PROGRAM-ID. TESTRUN. 

(c^ The specific instruction which caused 
the dump is located by subtracting the 
load address from the interrupt 
address (that is, subtracting 7D878 
from 7DFDC) . The result, 764, is the 
relative interrupt address and can be 
found in the object code listing. In 
this case the instruction in question 
is an AP (add decimal) . 



Program Checkout 251 



The left-hand column of the object 
code listing gives the compiler- 
generated card number associated with 
the instruction. It is card 66. As 
seen in the source listing, card 66 
contains the COMPOTE statement. 



Additional details about reading a dump 
are found in the chapter "Interpreting 
Output." 



ERRORS THAT CAN CAUSE A DUMP 



A dump can be caused by one of many 
errors. Several of these errors may occur 
at the COBOL language level while others 
can occur at the job control level. 

The following are examples of COBOL 
language errors that can cause a dump: 

1. A GO TO statement with no 
procedure-name following it may have 
been improperly initialized with an 
ALTER statement. The execution of 
this statement will cause an invalid 
branch to be taken and results will be 
unpredictable . 

2. Moves of or arithmetic calculations 
using numeric fields that have not 
been properly initialized. 

For example, neglecting to initialize 
the object of an OCCURS clause with 
the DEPENDING ON option, or 
referencing data fields prior to the 
first READ statement may cause a 
program interrupt and a dump. 

3. Invalid data placed in a numeric field 
as a result of redefinition. 

4 . Input/output errors that are 
nonrecoverable . 

5. Items with subscripts whose values 
exceed the defined maximum value can 
destroy machine instructions when 
moved. 

6 . Attempting to execute an invalid 
operation code through a system or 
program error. 

7. Generating an invalid address for an 
area that has address protection. 

8. Subprogram linkage declarations that 
are not defined exactly as they are 
stated in the calling program. 

9. Data or instructions can be modified 
by entering a subprogram and 
manipulating data incorrectly. A 



COBOL subprogram can acquire invalid 
information from the main program, 
e.g., a CALL statement using a 
procedure-name and an ENTRY statement 
using a data-name. 

10. An input file contains invalid data 
such as a blank numeric field or data 
incorrectly specified by its data 
description . 

The compiler does not generate a test 
to check the sign position for a valid 
configuration before the item is used 
as an operand. The programmer can 
test for valid data by means of the 
numeric class test and, by using the 
TRANSFORM statement, convert it to 
valid data under certain conditions. 

For example, if the units position of 
a numeric data item described as USAGE 
IS DISPLAY contained a blank, the 
blank could be transformed to a zero, 
thus forcing a valid sign. 

11. Division by zero without an ON SIZE 
ERROR clause will cause a data 
exception. 



LOCATING A DTF 



One or more DTF's are generated by the 
compiler for each file opened in the COBOL 
program. All information about that file 
is found within the DTF or in the fields 
preceding the DTF. See the chapter 
"Detailed Processing Capabilities" for the 
type of information available and its 
location . 

A particular DTF may be located in an 
execution-time dump as follows: 

1. Determine the order of the DTF address 
cells in the TGT from the DTF numbers 
shown for each file-name in the 
glossary. 

Note : Since the order is the same as 
the FD*s in the Data Division, the 
order can be determined from the 
source program if the SYM option was 
not used (i.e., no glossary was 
printed) . 

2. Find the relative starting address of 
the block of DTF cells from the TGT 
listing in the Memory Map. 

3. Calculate the absolute starting 
address of the block by adding the 
hexadecimal relocation factor for the i 
beginning of the object module as ^ 
given in the linkage editor MAP. 
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4- Allowing one fullword per DTF cell, 
count off the cells from the starting 
address found in step 3, using the 
order determined in step 1 to locate 
the desired DTF cell. 



If more than one DTF is generated for 
a file, the above procedure should be 
followed using the PGT and the SUBDTF 
cells rather than the TGT and the 
DTFADR cells. The order of multiple 
DTF's in storage is dependent on the 



the programmer should locate the contents 
of field B at the time of the interrupt. 
This can be done as follows: 

Cjj Locate data-name B in the glossary. 
It appears under the column headed 
SOURCE- NAME. Source-name B has been 
assigned to base locator 3 (i.e., 
BL =3) with a displacement of 050. 
The sum of the value of base locator 
and the displacement value 50 is the 
address of data-name B. 



a. INPUT 

b. OUTPUT 

c. I-O or INPUT REVERSED 



The following discussion illustrates the 
method of finding the DTF*s in the sample 
program in Figure 66. Letters identifying 
the text refer to letters in the program 
listing. 



Ej The DTF for FILE-1 precedes the DTF 
for FILE-2. 



(^ DTFADR CELLS begin at relative 
location 600. 



Qc) The Register Assignment table lists 
the registers assigned to each base 
locator. Register 6 has been assigned 
to BL =3. 



© 



The contents of the 16 general 
registers at the time of the interrupt 
are displayed at the beginning of the 
dump. Register 6 contains the address 
0007D978. 



M ) The location of data-name B can now be 
determined by adding the contents of 
register 6 and the displacement value 
50. The result, 7D9C8, is the address 
of the leftmost byte of the 4-byte 
field B. 




(gj Since the relocation factor is 7D878, 
the DTFADR CELLS begin at location 
7DE78 in the dump. 



H) The DTF for FILE-1 begins at location 
7D9E8, and the DTF for FILE-2 begins 
at location 7DA60. 



LOCATING DATA 



The location assigned to a given 
data-name may similarly be found by using 
the BL number and displacement given for 
that entry in the glossary, and then 
locating the appropriate one fullword BL 
cell in the TGT. The hexadecimal sum of 
the glossary displacement and the contents 
of the cell should give the relative 
address of the desired area. This can then 
be converted to an absolute address as 
described above. 

Since the problem program in Figure 66 
interrupted because of a data exception. 



Note : Field E contains F1F2F3C4. 
This is external decimal 
representation and does not correspond 
to the USAGE COMPUTATIONAL- 3 defined 
in the source listing. 



The location assigned to a given 
data-name may also be found by using 
the BL CELLS pointer in the TGT Memory 
Map. Figure 64 indicates that the BL 
cells begin at location 7DE6C (add 5FU 
to the load point address, 7D878, of 
the object module). The first four 
bytes are the first BL cell, the 
second four bytes are the second BL 
cell, etc. Note that the third BL 
cell contains the value 7D978. This 
is the same value as that contained in 
register 6. 



Note: Some program errors may destroy 
the contents of the general registers 
or the BL cells. In such cases, 
alternate methods of locating the 
DTF's are useful. 
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// JOB CATACHK , 

// OPTION NODECI^, LINK, LIST, LISTX.SYM, ERRS 
// EXEC FCOECL 



IBM DOS VS COBOL 



PP NO. 5746-CEl 



07.35.08 10/02/73 



SEQ 



CEL QUOTE, 

COOOl IDENTIFICATION DIVISION. 

C0002 PROGRAM- ID. TESTRUN. 

00003 AUTHOR. PROGRAMMER NAME. 

00004 INSTALLATION. NEW YORK PROGRAMMING CENTEl 
C0005 DATE-WRITTEN. SEPTEMBER 25,1973 

C0006 DATE -COMPILED. 10/02/73 

00010 ENVIRONMENT DIVISION. 

COOll CONFIGURATION SECTION. 

C0012 SOURCE- COMPUTER. IBM-370. 

C0013 OBJECT-COMPUTER. IBM-370. 

C0014 INPUT-OUTPUT SECTION. 

00015 FILE-CONTROL. 

00016 SELECT FILE-1 ASSIGN TO SYS008-UT-2t00-S. 

00017 SELECT FILE-2 ASSIGN TO SYS008-UT-2U00-S. 

00018 DATA DIVISION. 
C0019 FILE SECTION. 

00020 FD FILE-1 

00021 LABEL RECORDS ARE OMITTED 

00022 BLOCK CONTAINS 5 RECORDS 
C0023 RECORDING MODE IS F 

00024 RECORD CONTAINS 20 CHARACTERS 

00025 DATA RECORD IS RECORD-1. 
C0026 01 RECORD-1. 

00027 05 FIELD-A PIC X(20). 

00028 FD FILE-2 

00029 LABEL RECORDS ARE OMITTED 

00030 BLOCK CONTAINS 5 RECORDS 

00031 RECORD CONTAINS 20 CHARACTERS 

00032 RECORDING MODE IS F 
C0033 DATA RECORD IS RECORD-2. 

00034 01 RECCRD-2. 

00035 05 FIELD-A PIC X(2DT. 



® 



Figure 6 6. Sample Dump Resulting from Abnormal Termination (Part 1 of 6) 
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PP NO. 5746-CBl 



07.35.08 10/02/73 



C0036 
00037 
00038 
C0039 
C0040 
C0041 
C00U2 
00043 
CO0U4 
00045 
C0046 
00047 
00048 
00049 
C0050 
C0051 
00052 
00053 
C0C54 
C0G55 
C0056 
C0057 
C0058 
00059 
00060 
C0061 
00062 
00C63 
C0C64 
C0065 
C0C66 
C0067 
00068 
C0069 
00070 
C0071 
C0072 
00073 
CC074 
C0075 
00076 
00077 
C0078 
00079 
C0080 
00081 



WORKING-STORAGE SECTION. 
01 FILLER. 

02 KOUNT PIC S99 COMP SYNC. 

02 ALPHABET PIC X(26) VALUE IS "ABCDEFGHIJKLKNOPQRSTUVWXYZ" . 

02 ALPHA REDEFINES ALPHABET PIC X OCCURS 26 TIMES. 

02 NUMBR PIC S99 COMP SYNC. 

02 DEPENDENTS PIC X(26) VALUE "01234012340123401234012340". 

02 DEPEND REDEFINES DEPENDENTS PIC X OCCURS 26 TIMES. 
01 WORK-RECORD. 

05 NAME-FIELD PIC X. 

05 FILLER PIC X. 

05 RECORD-NO PIC 9999. 

05 FILLER PIC X VALUE IS SPACE. 

05 LOCATION PIC AAA VALUE IS "NYC". 

05 FILLER PIC X VALUE IS SPACE. 

05 NO-OF-DEPENDENTS PIC XX. 

05 FILLER PIC X(7) VALUE IS SPACES. 

02 A PICTURE S9(4) VALUE 1234. 

02 E REDEFINES A PICTURE S9(7) COMPUTATIONAL- 3 . 
PROCEDURE DIVISION. 
BEGIN. READY TPvACE. 

NOTE THAT THE FOLLOWING OPENS THE OUTPUT FILE TO BE CREATED 

AND INITIALIZES THE COUNTERS. 
STEP-1. OPEN OUTPUT FILE-1. MOVE ZERO TO KOUNT, NUMBR. 

NOTE THAT THE FOLLOWING CREATES INTERNALLY THE RECORDS TO Bt 

CONTAINED IN THE FILE, WRITES THEM ON TAPE, AND DISPLAYS 

THEM ON THE CONSOLE. 
STEP-2. ADD 1 TO KOUNT, NUMBR. MOVE ALPHA (KOUNT) TO 

NAME-FIELD. 

COMPUTE B = B + 

MOVE DEPEND (KOUNT) TO NC-OF-DEPENDENTS . 

MOVE NUMBR TO RECORD-NO. 
STEP-3. DISPLAY WORK- RECORD UPON CONSOLE. WRITE RECORD-1 FROM 

WORK- RECORD. 
STEP-4. PERFORM STEP-2 THRU STEP-3 UNTIL KOUNT IS EQUAL TO 26. 

NOTE THAT THE FOLLOWING CLOSES THE OUTPUT FILE AND REOPENS 

IT AS INPUT. 
STEP- 5. CLOSE FILE-1. OPEN INPUT FILE- 2. 

NOTE THAT THE FOLLOWING READS BACK THE FILE AND SINGLES 

OUT EMPLOYEES WITH NO DEPENDENTS. 
STEP-6. READ FILE-2 RECORD INTO WORK-RECORD AT END GO TO STEP-8. 
STEP-7. IF NO-OF-DEPENDENTS IS EQUAL TO "0" MOVE "Z" TO 

NO-CF-DEPENDENTS. EXHIBIT NAMED WORK-RECORD. GO TO STEP-6. 
STEP-8. CLOSE FILE-2. 

STOP RUN. 



1. ® 




Figure 66. Sample Dump Resulting from Abnormal Termination (Part 2 of 6) 
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IBM DOS VS COBOL 
INTRNL NAME LVL SOURCE NAME 



REL 1.0 



PP NO. 5746-CBl 



DNM=1-148 


FD 


FILE-1 


DNM=1-179 


01 


RECORD- 1 


DNM=l-200 


02 


FIELD-A 


DNM=1-217 


FD 


FILE-2 


DNM=l-2l»8 


01 


RECORD- 2 


DNM=l-269 


02 


FIELD-A 


DNM=l-289 


01 


FILLER 


DNM=l-308 


02 


KOUNT 


DNM=l-323 


02 


ALPHABET 


DNM=l-3m 


02 


ALPHA 


DNM=l-359 


02 


NUMBR 


DNM=l-371t 


02 


DEPENDENTS 


DNM=l-394 


02 


DEPEND 


DNM=l-l»10 


01 


WORK-RECORD 


DNM=1-43U 


02 


NAME-FIELD 


DNM=l-454 


02 


FILLER 


DNM=l-473 


02 


RECORD- NO 


DNM=l-492 


02 


FILLER 


DNM=2-000 


02 


LOCATION 


DNM=2-018 


02 


FILLER 


DNM=2-037 


02 


NO-OF-DEPENDENTS 


DNM= 2-063 


02 


FILLER 


DNM=2-082 


01 


RECORDA 


DNM=2-102 


02 


* r-N 


DNM=2-113 


02 


B . /n 



BASE 


DISPL 


INTRNL NAME 


DEFINITION 


USAGE 


DTF=01 




DNM=1-148 






DTFKT 


BL=1 


000 


DNM=1-179 


DS 


0CL20 


GROUP 


BL=1 


000 


DNM=l-200 


DS 


20C 


DISP 


DTF=02 




DNM=1-217 






DTFMT 


BL=2 


000 


DNK=l-248 


DS 


0CL20 


GROUP 


BL=2 


000 


DNM=l-269 


DS 


20C 


DISP 


BL=3 


000 


DNM=l-28 9 


DS 


0CL56 


GROUP 


BL=3 


000 


DNK=l-308 


DS 


IH 


COMP 


BL=3 


002 


DNM=l-323 


DS 


26C 


DISP 


BL=3 


002 


DNM=1-341 


DS 


IC 


DISP 


BL=3 


OIC 


DNM=l-359 


DS 


IH 


COiMP 


BL=3 


OlE 


DNM=l-374 


DS 


26C 


DISP 


BL=3 


OlE 


DNM=l-394 


DS 


IC 


DISP 


BL=3 


038 


DNK=1-410 


DS 


0CL2G 


GROUP 


BL=3 


038 


DNK=l-434 


DS 


IC 


DISP 


BL=3 


039 


DNK=l-454 


DS 


IC 


DISP 


BL=3 


03A 


DNM=l-473 


DS 


4C 


DISP-NM 


BL=3 


03E 


DNM=l-492 


DS 


IC 


DISP 


BL=3 


03F 


DNM=2-000 


DS 


3C 


DISP 


BL=3 


042 


DNM=2-018 


DS 


IC 


DISP 


BL=3 


043 


DNM=2-037 


DS 


2C 


DISP 


BL=3 


045 


DNM=2-063 


DS 


7C 


DISP 


BL=3 


050 


DNM=2-082 


DS 


0CL4 


GROUP 


BL=3 


050 


DNM=2-102 


DS 


4C 


DISP-Nil 


BL=3 


050 


DNM=2-113 


DS 


4P 


COKP-3 



07.35.08 10/02/73 



R C M 



MEMORY MAP 



SAVE AREA 


00400 


SWITCH 


00448 


TALLY 


0044C 


SORT SAVE 


00450 


ENTRY- SAVE 


00454 


SORT CORE SIZE 


00458 


NSTD-REELS 


004 5C 


SORT RET 


0045E 


WORKING CELLS 


00460 


SORT FILE SIZE 


00590 


SORT MODE SIZE 


00594 


PGT-VN TBL 


00598 


TGT-VN TBL 


0059C 


SORTAB ADDRESS 


005AO 


LENGTH OF VN TBL 


005A4 


LNGTH OF SORTAB 


005A6 


PGM ID 


005A8 


A(INITl) 


005E0 


UPSI SWITCHES 


005B4 


DEBUG TABLE PTR 


005BC 


CURRENT PRIORITY 


005C0 


TA LENGTH 


005C1 


PROCEDURE BLOCKl PTR 


005C4 


UNUSED 


005C8 


RESERVED 


005CC 


VSAM SAVE AREA ADDRESS 


005E0 


UNUSED 


005D4 


RESERVED 


005DC 


OVERFLOW CELLS ^'-^ 
BL CELLS M { NJ 


005F4 


005F4 . 


DTFADR CELLS ^^ 


00600 " { 


FIB CELLS 


00608 


TEMP STORAGE 


00608 


TEMP STORAGE-2 


00610 


TEMP STORAGE- 3 


00610 


TEMP STORAGE- 4 


00610 


BLL CELLS 


00610 


VLC CELLS 


00614 


SBL CELLS 


00614 


INDEX CELLS 


00614 


SUBADR CELLS 


00614 


ONCTL CELLS 


0061C 


PFMCTL CELLS 


0061C 


PFMSAV CELLS 


0061C 


VN CELLS 


00620 


SAVE AREA =2 


00624 


XSASW CELLS 


00624 


XSA CELLS 


00624 


PARAW CELLS 


00624 


RPTSAV AREA 


00628 


CHECKPT CTR 


00628 


lOPTR CELLS 


00628 







Figure 66. Sample Dump Resulting from Abnormal Termination (Part 3 of 6) 
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IBM DOS VS COBOL 



PP NO. 5746-CEl 



OT-T^-riB in/ri'j/T-j 



iEGISTEJ 


R ASSIGNMENT 


REG 6 


BL =3 -* 


REG 7 


BL =1 


REG 8 


BL =2 



66 
67 



000708 


48 


30 


C 


03A 




00070C 


4A 


30 


6 


000 




000710 


4E 


30 


D 


208 




000714 


D7 


05 


D 


208 D 


208 


00071A 


94 


OF 


D 


20E 




00071E 


4f 


30 


D 


208 




000722 


40 


30 


6 


000 




000726 


48 


30 


C 


03A 




00072A 


4A 


30 


6 


OIC 




00072E 


4E 


30 


D 


208 




000732 


D7 


05 


D 


208 D 


208 


000738 


94 


OF 


D 


20E 




00073C 


4F 


30 


D 


208 




000740 


40 


30 


6 


OIC 




000744 


41 


40 


6 


002 




000748 


48 


20 


6 


000 




00074C 


4C 


20 


C 


03A 




000750 


lA 


42 








000752 


5B 


40 


C 


038 




000756 


50 


40 


D 


214 




00075A 


58 


EO 


D 


214 




00075E 


D2 


00 


6 


038 E 


000 


000764 


FA 


30 


6 


050 C 


03C 



©— 



LH 


3,03A(0,12) 


LIT+2 


AH 


3,000(0,6) 


DNM=l-308 


CVB 


3,208(0,13) 


TS=01 


xc 


208(6, 13), 208(13) 


TS=01 


NI 


20E(13),X*0F' 


TS=01+6 


CVB 


3,208(0,13) 


TS=01 


STH 


3.000(0.6) 


DNM=l-308 


LH 


3,03A(0,12) 


LIT+2 


AH 


3,01C(0,6) 


DKM=l-359 


CVD 


3,208(0,13) 


TS=01 


XC 


208(6, 13), 208(13) 


TS=01 


NI 


20E(13),X'0F= 


TS=01+6 


CVB 


3,208(0,13) 


TS=01 


STH 


3,01C(0,6) 


DKM=l-359 


LA 


4t, 002(0, 6) 


DNM=1-341 


LH 


2,000(0,6) 


DilM=l-308 


MH 


2,03A(0,12) 


LIT+2 


AR 


4,2 




S 


4,038(0,12) 


LIT+0 


ST 


4,214(0,13) 


SES=1 


L 


14,214(0,13) 


SBS=1 


MVC 


038(1, 6), 000(14) 


DNM=l-434 


AP 


050(4,6),03C(1,12) 


DNM=2-113 



DNK=1-341 
LIT+4 



// EXEC LNKEDT 



PHASE XFR-AD LOCORE HICORE DSK-AD 
PHASE*** 07D878 07D878 07F2AF 05F OF 4 



♦ UNREFERENCED SYMBOLS 

002 UNRESOLVED ADDRESS CONSTANTS 



ESD TYPE 


LABEL 


LOADED 


REL-FR 


CSECT 


TESTRUN 


07D878 


07D878 


CSECT 


IJFFBZZN 


07E278 


07E278 


* ENTRY 


IJFFZZZN 


07E278 




♦ ENTRY 


IJFFBZZZ 


07E278 




* ENTRY 


IJFFZZZZ 


07E278 




CSECT 


ILBDSAEO 


07F128 


07F128 


ENTRY 


ILEDSAEl 


07F170 




CSECT 


ILBDMNSO 


07F120 


07F120 


CSECT 


ILBDDSPO 


07E628 


07E628 


ENTRY 


ILBDDSPl 


07EA28 




CSECT 


ILBDIMLO 


07F0C8 


07F0C8 


CSECT 


ILBDDSSO 


07EDA0 


07EDA0 


ENTRY 


ILBDDSSl 


07F000 




ENTRY 


ILBDDSS2 


07EFF8 




ENTRY 


ILBDDSS3 


07F0B8 




ENTRY 


ILBDDSS4 


07EDC6 




ENTRY 


ILBDDSS5 


07£E72 




ENTRY 


ILBDDSS6 


07EED2 




ENTRY 


ILBDDSS7 


07EE9C 




ENTRY 


ILBDDSS8 


07EDF6 




CSECT 


IJJCPDV 


07EB58 


07EB58 


ENTRY 


IJJCPDVl 


07EB58 




* ENTRY 


IJJCPDV2 


07EB58 




WXTRN 


STXITPSW 






HXTRN 


ILBDDBG2 







— <D 



// ASSGN SYS008,X'4S2' 
// ?XEC 



Figure 66. Sanple Dump Resulting from Abnormal Termination (Part 4 of 6) 



Program Checkout 257 



OSOjI fROGRA^i CritCK INTEKKUfilON 

CSC 01 JOB DMACHK CANCELED 



HJiX ijOcAilON 0/Ui:'UC - CONDITION CODE 2 - DATA EXCEPTION 



w 



FP REG 
CR 0-F 



DATACHK 

0007DE78 0007DF80 00000001 00000001 
0007DBA8 0007E1FC 0007D878 0007D878 
00000000 00000000 00000000 00000000 
OOtOOOFF OlOODDOO FFFFFFFF FFFFFFFF 
00000000 00000000 00000000 00000000 
BG ADDR IS 000360 



© 



0007D97A 5007E22C 0007D978 0007DB40 
0007DEA0 0007DC78 0007D97A 0007E628 
00000000 00000000 00000000 booooooo 
00000000 00000000 00000000 00000000 
00000000 00000000 CUOOOOOO 00000200 



ccoooo 


00000000 


00000000 


00000000 


00000000 


00000000 


00000360 


00000000 


00000000 


C0C02O 


070DOOOO 


000076CE 


040D0000 


000074DA 


OOOCOOOO 


oooooobo 


070C2000 


0000071E 


ocooao 


0000DE68 


08000000 


0000DE58 


00000000 


EFFCC798 


012A88EA 


040C0000 


000009BE 


C00060 


040COOOO 


0000097A 


OOOCOOOO 


0000980C 


04080000 


OOOOC09E 


040C0000 


000008F8 


COC080 


00000400 


00000000 


00020007 


00020001 


1207F003 


00000000 


OOOCOOOO 


00000000 


COOOAO 


00000000 


00000000 


00000000 


000002CO 


00000000 


00000000 


OOOOOOOE 


00000000 


COOOCO 


00000000 


— SAME— 














C00360 


F1F061F0 


F261F7F3 


FOOOFOOO 


00000000 


00000000 


00000000 


C4C1E3C1 


C3C8D240 


000380 


0011D7FF 


0007F2AF 


0007F2AF 


00000010 


0017D7FF 


F97F5CD3 


A8A07CDO 


00A63891 


C003A0 


38983D4A 


3D4B0000 


374C3750 


375438F1 


F0F0F2F7 


F3F2F7f5 


00003544 


00000000 


C003C0 


3EF00000 


363C36BC 


372CC010 


00000010 


000070EC 


00000000 


OC0030DC 


34440000 


C003E0 


00000000 


036010E0 


00000448 


C0C00340 


40404040 


40404000 


40404040 


40404000 


oooaoo 


0000528C 


00002742 


063E05FA 


00003A40 


00001F42 


00004058 


00004F5E 


000073D8 


0001*20 


OOOOFOOO 


0300505E 


0014002C 


00030000 


000O5F78 


00000000 


000072F5 


00005204 


000140 


40800000 


0000070E 


00008350 


00005100 


000051B4 


000052CC 


00100010 


00000000 


C00i»60 


00000000 


000065F8 


00000000 


000030DO 


000004FO 


000070F5 


00003C5A 


OOOCOOOO 


000480 


00009812 


000088C8 


00000544 


00000000 


0000BC88 


00007F50 


000032FC 


00003314 


0004AO 


00081018 


00200000 


00000000 


00000000 


00000000 


000031A6 


OOOCOOOO 


OOOCOOOO 


C004CC 


00000000 


00000000 


00000005 


03C10401 


OOOOEDOO 


OOOOCDFO 


O0bOD5F0 


00005378 


0004E0 


000053B8 


00000000 


00000000 


0007D7FF 


FF010174 


015502A0 


FF0C0045 


O0OOC6EC 


000500 


OOOOCOAO 


00003868 


0OOCA1E8 


00000000 


OOOAOOOO 


00001000 


00002000 


00003000 


000520 


070DOOOO 


000076C4 


00000360 


00000000 


8000750E 


900075CO 


400053C8 


00004F5E 


000540 


00080700 


00000000 


00000000 


00000000 


04FC0552 


00000000 


OOOCOOOO 


OOOCOOOO 


000560 


0000318C 


0000DEE8 


00000008 


00020406 


080A0C0E 


00183048 


607890A8 


OOCOOCCO 


000580 


00000000 


00830083 


00830083 


00830083 


00830083 


00830083 


00830083 


00830083 


0005AO 


00830083 


— SAME — 














C005CC 


00830083 


00830083 


00000083 


83838300 


80020000 


00007888 


OOOCOOOO 


0000BBA5 


0005EO 


06B006BO 


06B006B0 


06E006B0 


4EE0056A 


06B006BO 


06B006BO 


06B006BO 


06B006BO 


000600 


06B006B0 


06B006B0 


06B006BO 


06B006B0 


4iBB001F 


41BB0010 


18F69503 


04454770 


C00620 


06604590 


06D447F0 


066006B0 


06B006B0 


06E006B0 


06B006B0 


06B041BB 


001F06B0 


000640 


06B041BB 


001B4570 


06A85890 


041441F0 


92161211 


47700660 


41F09314 


94633006 


000660 


42B0A001 


58B00514 


96OCA00F 


07FF960C 


A00F44OO 


B52§077F 


920003CF 


928305C9 



Figure 66. Sample Dump Resulting from Abnormal Termination (Part 5 of 6) 
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Dr 



07E800 
07E820 
07E840 
07D860 
07E880 
07E8A0 
07E8C0 
07E8E0 
07E900 
07E920 
07E9aO 
07E960 
07E980 
07E9flO 
07C9CQ 



07E9E0 
07EA00 
07Efl20 



DATACHK 

D7C8C1E2 
0007EC78 
5007E22C 
00000000 
17F0F082 
0011B7FF 
00000000 
0007EBA8 
58E0C000 
90ECDOOC 
0007EEflO 
00000000 
C7C8C9D1 
F0F1F2E3 
40101040 



6COOOO00 
E2FOF0F8 
0107EAD8 



C55C5C5C 
0007D97A 
0007D978 
00000000 
0007D878 
0007F8C8 
00000000 
0007E1FC 
58D0F0CA 
185D989F 
0007DC78 
F1F061F0 
D2D3D4D5 
F4F0F1F2 
OOOOOOOl 



071D2000 
0007E628 
0007DB40 
00000000 
0007E878 
0A1618 0C 
00000000 
0007E878 
9500EOOO 
F0EA9110 
0007EF08 
F261F7F3 
D6E7D8D9 
F3F4F0F1 



00000000 
40400162 
20000064 



•■1F2F3C4I' 



|00009200 
lOOOOOOO 



0007DFE2 

0007EE78 

0007DBA8 

00000000 

0011D7FF 

00000000 

00000000 

0007D878 

4770F0A2 

D0480719 

0007E1E2 

F0F74BF3 

E2E3E4E5^-^ji 

F2F3F4F0( m)c 

00000000^-^0 



0007E1FC 
0007EF80 
0000844B 
OOCCOOOO 
0O0OE8E6 
182F07F1 
00000000 
0007EEA0 
9610D048 
07FF0700 
C3E6C2C6 
F54BF0F8 
E6E7E8E9 
107DB78 
01010014 



000001081 0007DA20 
04000000 OOCCOOOO 
0007EB40 0007DB40 00000014 



0007D878 
OOOOOOOl 
E56753BE 
OOOOOCOO 
0000DB64 
0007D878 
OOOOOOOC 
0007DC78 
92FFEO0O 
0007E1FC 
F3F0F0F0 
10604780 
OOOIFOFI 
000040D5 
00000000 
00000000 
86BCF018 
0007DBA3 



0007E878 
OOOOOOOl 
00000000 
05F00700 
8C000015 
D7C8C1E2 
0007D978 
00000000 
47F0F0AC 
0007E878 
E3C5E2E3 
0001C1C2 
F2F3F4F0 
E8C34000 
OOCCOOOO 
0007E278 
41E0E001 
00640063 



0007EEA0 
0007D97A 
COOOCOOO 
900EF00A 
80000015 
C55C5C5C 
0007DAD8 
58C0F0C6 
98CEF03A 
C007D878 
D9E4D540 
C3C4C5C6 
F1F2F3F4 
00404040 
00000000 
1160E2E8 
58201044 
00000000 



07EA4 OOOOOCOO 4007F128 
*' |00008200 



07EA6C 
07EA8 
C7EAA0 
07EAC0 
07EBOO 
07EE20 
07BB40 
07EE60 
07EB80 
C7EEA0 
07EBC0 
07EBE0 
07EC00 
07EC20 
07EC40 
07EC60 
07EC80 
07ECAC 
07ECC0 
07ECE0 
C7ED00 
07ED6C 
07ED80 
07EEA0 
07EDC0 
07EEE0 
07EEOO 
07EE20 
^ 07CE40 
JV 07EE60 
07BE80 
07EEAO 
07EEC0 
07EEE0 
07EF00 
07EF2C 
C7EF40 
07EF60 
07EF80 
07EFA0 
07EFC0 
07EFE0 
07E00O 
07E020 
07E040 
07E060 
07E08C 
C7ECAC 
07E0CO 
07E0EO 
07E100 
07E120 
07E140 



00000000 
0CO7BC10 
OOOOOOOC 
OOOOOCOO 
0007ECF8 
FFFEFFFF 
OOC08000 
0207BD38 
00198800 
F14C91C8 
430E0001 
0C1447F0 
58140038 
4BE0F250 
F1A85820 
F2324780 
47F0F16E 
7010004B 
0OO0D8E6 
40404040 
40404040 
4007BF54 
C007B978 
0007E628 
50002000 
07070607 
E3C5E2E3 
F0325810 



01010014 

00001081 00C7DA98 
OOCCOOOO 
000C0C14 



20000000 
OOCCOOOO 
— SAME — 
OOOOOCOO 
OOOOOCOO 
FFFFFFFF 
00000107 
20000050 
0019C6C0 
40154710 
89C00019 
F0C44100 
501CF2CA 
B201F210 
F20A4122 
F1444800 
41E0F14C 
OOOOOCOO 
C007B9E8 
— SAKE — 
40404040 
0007E628 
0007BB40 
C007BE78 
4A50F060 
07070707 
B9E4D540 
F0789101 



00000100 
OOOOOOOC 
0007F120 
0C07E07E 
5B5BC2B6 
60B9C5C3 
C51F0001 
4500FOOC 
5870D1F4 
4830C03A 
C03A4A3C 
48206000 
C03C4140 
E00C9240 
4004F6F9 
60385810 
C004C51F 
60004930 
00014004 
4500F00C 
500CFCC8 
58F0C004 
41FCCC28 
58F0C018 



0C0C02A8 
OCOOOOIC 
00Q7E628 
0007E092 
D7C5D540 
D6B9C4BE 
4004F6F0 
C007B9E8 
B2016C0C 
4A306000 
601C4E30 
4C20CC3A 
601E4820 
60444830 
40404CFO 
D2001841 
CCC14C04 
C03E58F0 
F7F44040 
OOOOOCOO 
4500F00C 
051F0001 
D2021025 
07FF5810 



00008000 
C207DB10 
FFFFDBEl 
0007BBE8 
4120EO00 
12004780 
FC949180 
88CC0019 
O0OC1B4O 
4110F20A 
E000581C 
OC0058E0 
F22E9400 
9101F233 
COOOCOOO 
5007E22C 

40404040 
0007EE78 
CC07BBA8 
OC07FOOO 
4A20F06C 
OOOOOOOC 
00C7D878 
10004710 



B4C5E3C 

OOCCOOOO 

CQ07FOC8 

0007E146 

5B5EC2C3 

58F0C004 

40404076 

OA02410C 

C038B201 

4E30B208 

D208B705 

1A425B40 

60004C20 

6C1C4E30 

58FCC004 

58F01010 

F7F14040 

C024078F 

40585810 

OA025800 

OOCCOOOO 

4004F7F7 

F00158F0 

C01C07F1 



OOCCOOOO 
OOCCOOOO 
86BCF018 
00000000 

00000107 
2CCC0014 
20000082 
COCCCCCO 
47000000 
F07442CE 
40154710 
43EE00OC 
58E400CC 
5010F202 
F2420ACC 
F23E58F0 
F2325820 
478CF16E 
0007EF08 
F16E9025 

4C4C0000 
0007DF80 
0007E1FC 
00C7EE40 
183047FO 
OOOOOOOC 
C9B3C2C4 
F03296C1 



OOCCOOOO OOCCOOOO OOOOOCOO OOOOOCOO 

0CC7E278 1168E2E8 E2F0F0F8 40400272 

41E0E0C1 58201044 0207EBA8 00000064 

00640063 OOOOOCOO C0C7F170 CC07F128 



b007B97fl 
OC07DF70 
0007E174 
D3B6E2C5 
051F0001 
582CD1F4 
E20058F0 
6C1CC038 
B705E208 
D208D208 
C0385040 
CC3A1A42 
B2C8F331 
051F0002 
45ECF00C 
400F5800 
581OCO0C 
D20C94EF 
B200411C 
0A02410C 
40404040 
101C45EC 
58F0CC04 



CC07EB90 
4120E00C 
4710F132 
C007E3E8 
000CF0C4 
00OC96O1 
F0E84100 
89EC0019 
1A4041EE 
D201F2CO 
91801002 
F1F207FF 
F23A58EC 
001C004B 
OOCCOOOO 
F21290BC 

COOOCOOO 
0007BE40 
0CO7E878 
00014720 
F036B200 
E2C1B4B7 
B6E2E8F0 
00000000 



t I0007DB4C I 0C07EBA8" 



OOOOOCOO 
47000000 
47F0F15E 
02050202 
18E44BE0 
F23247F0 
000847FO 
88EC0019 
000C12EE 
40069108 
4710F114 
47F0F104 
F23E58F4 
OOCCOOOO 
OOCCOOOO 
40404040 

0007BF78 
■0000D8E6 
C007D878 
C007BF78 
50002000 
D3C54040 
F3F090C2 
ODOOOOQO 



9802E068 
0007E05E 
0007E05E 
5E5BC2C6 
4004F5F7 
411CC040 
C00805EF 
58F0C004 
E208940F 
940FE20E 
B21458E0 
5B40C038 
603AE20E 
0CC00014 
5C2CE1F4 
B2205000 
C7F158CC 
10201801 
C050CA02 
D20458FO 
5810E204 
F0085020 
C51F00C1 



I0007D97.81 
47FE0002 
0007E100 
4C0B1F88 
C3B4E4B3 
404040B2 
5800D2C0 
5810D20C 
051F0001 
B20E4F30 
4F30D208 
E214D200 
5C40D218 
96FC603D 
OBCOOIFC 
5870D1F4 
B21C5800 
D21C50CO 
18404110 
411CC040 
CC0805EF 
58FOC028 
D1F85880 
4C04F7F8 



0007E450 
OOCOFFFF 
91084015 
0C07ECE0 
F24C430E 
F0464800 
FCC418E4 
19E04780 
4780F132 
40154780 
0A079108 
0CC0F233 
00100A09 
OOOOOOOC 
0007B9E8 
40404040 

0007BB40 
0007B9E8 
CC07EEA0 
0007EDA0 
OOCCOOOO 
00C7B878 
B0689120 
F0549110 



P007D9E8 
OOC7E05E 
0007E14C 
OOOOOOOl 
COOOCOOO 
9640B048 
^84005F0 
96101020 
4004F6F4 
D2084030 
403C601C 
6038E0C0 
58E0B218 
58FCC004 
C038FFFF 
5810B220 
C0205000 
B22058F0 
C04805F0 
5800B204 
5810E204 
91201010 
B1F8B213 
40404080 



02050202 
FFFFFFFF 
OOOOOCOO 
OOOOOCOO 
00C089OO 
F23047FC 
4EECF24E 
F08C4100 
50E0F1F2 
F11C18E4 
40204710 
1E009101 
41ECF11C 
OOCCOOOO 
0007DB40 
40404040 

01000000 
5007E22C 
CC07DF80 
4007E88E 
OOCCOOOO 
OOOOOCOO 
E00C478C 
000002EO 
0007BA60I 



B7C5DS40 
C007E1A4 
ICOOOOIA 
E6E6B9B2 
58F0C004 
5CC0F008 
5020B1F4 
40404004 
60004830 
41406002 
FA306C50 
B2006043 
051F0001 
B2137000 
07F158F0 
B22C4830 
C004051F 
50C0F008 
184005F0 
96101020 
071F1841 
60388000 
5820C02C 



^ 



Figure 66. Sample Dump Resulting from Abnormal Termination (Part 6 of 6) 
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EXECUTION STATISTICS 



The DOS/VS COBOL Compiler provides 
several methods for testing, debugging, and 
optimizing programs. Use of the symbolic 
debugging features is an efficient method 
for testing and debugging a program, and is 
described in the chapter "Symbolic 
Debugging Features". The chapter entitled 
"Program Checkout" contains information 
useful for testing and debugging programs 
without the symbolic debugging features. 
The OPT option, described in the chapter 
"Preparing COBOL Programs for Processing", 
is an efficient method for automatically 
optimizing a program. 

This chapter describes execution 
statistics — how they may be obtained, 
some sample output, and some uses of the 
output. 



OBTAINING EXECUTION STATISTICS 



Execution statistics are invoked via the 
CBL card at compile time. No source 
language coding changes are required. The 
execution frequency statistics option, 
COUNT, facilitates testing, debugging, and 
optimizing by providing the programmer with 
verb counts at the following times. 

• STOP RUN 



3. To obtain execution statistics if 
COUNT is requested for one of many 
program units, either all programs 
must be compiled by at least DOS/VS 
Release 2 compiler, or the program 
must terminate in a program unit 
compiled on at least a DOS/VS COBOL 
Release 2 compiler, or the program 
must terminate in at least a DOS/VS 
COBOL library Release 2 subroutine. 

4. If COUNT is requested, the user must 
specify the SIZE parameter on his load 
module EXEC card. The dynamic space 
required for COUNT is approximately 
512 bytes plus 80 bytes per program 
unit being monitored, and four bytes 
per count block (see the compiler 
output statistics). The requirements 
for each program unit are rounded to 
the next 128-byte boundary. 

5. The OTHERWISE verb is treated as if 
the user coded the ELSE verb. 



• GOBACK in the main program 

• Abnormal termination of a job 

When COUNT is specified, the following 
items should be taken into account: 

1. If COUNT and STXIT are desired, either 
STIXIT must be requested in the 
program unit requesting COUNT, or, the 
program unit requesting COUNT must be 
entered before the program unit 
requesting STIXIT. 

2. When COUNT is specified, the compiler 
divides the program into blocks of 
verbs. When the statistics are 
printed, the last block of verbs 
executed in each program unit is 
indicated. If the program abnormally 
terminates, the statement causing the 
abnormal term.ination can be determined 
(by using the symbolic debugging 
features, for example). The 
programmer should then subtract one 
from the verb count for each verb 
flagged which follows the abending 
verb. 



Debugging and Testing 

The execution statistics clearly 
identify the following areas of the 
program: 

• Untested and weakly tested areas of the 
program 

• The last blocks entered and executed 

• Possible sources of unnecessary code 

• The most heavily used parts of the 
program; that is, those parts most 
susceptible to changes. 



OPTIMIZATION METHODS 



Based on execution frequency and timer 
statistics, the following types of 
optimization can be implemented by the 
user: 
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• Resequencing the program 



Common Expression Elimination 



• Insight into SYMDMP 

• Common expression elimination 

• Backward movement 

• Unrolling 

• Jamming 

• Unswitching 

• Incorporating procedures inline 

• Tabling 

• Efficiency guidelines 

Note, however, that each optimization 
technique can result in more inefficient 
code if the statistics used in optimizing 
the program are not representative of the 
normal program flow. In addition, it is 
recommended that any optimization methods 
implemented be documented in the prog ram - 



Resequencing the Program 



This technique is designed to eliminate 
unnecessary arithmetic calculations. An 
arithmetic expression calculation is 
considered unnecessary if it represents a 
value calculated elsewhere that will always 
be used without modification. One such 
example would be an arithmetic expression 
whose operands are not redefined or 
reevaluated, but the expression is 
recalculated. 



Backward Movement 



This technique facilitates moving 
calculations and other operations from an 
area of code frequently executed to an area 
less frequently executed. For example, an 
expression calculated within a PERFORMed 
procedure (using a Format 2, 3, or 4 
PERFORM Statement) which always yields the 
same value for that PERFORM statement could 
be calculated in-line or in another 
procedure which would be PERFORMed just 
prior to the regularly PERFORMed procedure. 
Another example might be an expression 
which is calculated in many procedures 
which are often PERFORMed in succession. 
This expression could be removed from all 
the procedures and calculated just once 
prior to the procedures. 



The COBOL Procedure Division should be 
organized as follows: Unrolling 



3. 



All frequently-used paragraphs or 
sections should be located near the 
routines that use them« 

All infrequently-used paragraphs or 
sections should be grouped together 
and apart from frequently-used 
routines - 

The most frequently-referenced data 
items should be placed in the 
beginning of the Working-Storage 
Sections . 



Procedures which are frequently executed 
may be expanded so that the statements 
within the procedure are repeated, with 
slight modification, to reduce the 
procedure overhead. For example, 

PERFORM YEARLY-GROSS-CALC VARYING 
WEEK-NO 

FROM 1 BY 1 UNTIL WEEK-NO 
GREATER THAN 52. 

YEARLY-GROSS-CALC . 

ADD GROSS-SALARY (WEEK-NO) TO 
YEARLY -GROSS 



Insight into SYMDMP Output 



The area where dynamic symbolic dumps 
are to be used can be pointed to by the 
execution statistics. Knowledge of what 
area of code is executed and how often it 
is executed should give the user 
information on what sections should be 
further investigated. 



could be replaced by 

PERFORM YEARLY-GROSS-CALC VARYING 
WEEK-NC 

FROM 1 BY U UNTIL WEEK-NO 
GREATER THAN 52. 

YEARLY-GROSS-CALC. 

ADD GROSS-SALARY (WEEK-NO), 

GROSS-SALARY (WEEK-NO+1) , 



Execution Statistics 260.1 



GROSS-SALARY (WEEK-NO+2) , GROSS 
SALARY (WEEK-NO+3) 
YEARLY-GROSS. 

In addition, indexing might be useful in 
this example. 



Jamming 



In some instances, two procedures can be 
merged into one procedure, thereby saving 
some procedure overhead. An example of 
this might be replacing 

MOVE TO WEEK -NUM. . 

PERFORM YEARLY-GROSS-CAL 52 TIMES. 

MOVE TO WEEK- NUM. 

PERFORM YEARLY- NET-CAL 52 TIMES. 



by 



ADD JOB-COST (COUNT) TO 
TOTAL- J03-C0ST. 

IF SWITCH = ADD JOB-EXPENSE 
(COUNT) TO TOTAL-EXPENSES ELSE 
ADD JOB-EXPENSE (COUNT) OVERHEAD TO 
TOTAL- EXPENSES. 
ADD JOB- INCOME (COUNT) TO 
TOTAL- INCOME. 

IF SWITCH = ADD JOB-PROFIT (COUNT) 
TO TOT'AL-PROFITS ELSE 
COMPUTE TOTAL-PROFITS = 
TOTAL- PROFITS + JOB -INCOME (COUNT) 
- JOB-COST (COUNT) - JOB-EXPENSE 
(COUNT) - OVERHEAD. 



COUNT = 

IF SWITCH = 

PERFORM JOB-TOTAL-CAL-0 JOB-NUM 

TIMES ELSE 

PERFORM JOB-TOTAL-CAL-1 JOB-NUM 

TIMES. 



by 



YEARLY-GROSS-CAL . 

ADD 1 TO WEEK- NUM. 

ADD GROSS-SALARY (WEEK-NUM) to 

YEARLY-GROSS. 
YEARLY- NET-CAL. 

ADD 1 TO WEEK-NUM. 

ADD NET-SALARY (WEEK-NUM) TO 

YEARLY-NET. 



MOVE TO WEEK-NUM. 

PERFORM YEARLY- CAL 52 TIMES. 



YEARLY-CAL. 

ADD 1 TO WEEK-NUM. 

ADD GROSS-SALARY (WEEK-NUM) to 

YEARLY-GROSS. 

ADD NET- SALARY (WEEK-NUM) TO 

YEARLY- NET. 



JOB-TOTAL-CAL-0. 

ADD 1 TO COUNT. 

ADD JOB-COST (COUNT) TO 

TOTAL- JOB- COST. 

ADD JOB-EXPENSE (COUNT) TO 

TOTAL-EXPENSES. 

ADD JOB-INCOME (COUNT) TO 

TOTAL-INCOME- 

ADD JOB-PROFIT (COUNT) TO 

TOTAL-PROFITS. 
JOB-TOTAL-CAL-1. 

ADD 1 TO COUNT 

ADD JOB-COST (COUNT) TO 

TOTAL-JOB-COST 

ADD JOB-EXPENSE (COUNT) , OVERHEAD TO 

TOTAL- EXPENSE 

ADD JOB- INCOME (COUNT) TO 

TOTAL- INCOME 

COMPUTE TOTAL- PROF ITS = 

TOTAL- PROFITS + JOB- INCOME (COUNT) 

- JOB-COST (COUNT) - JOB-EXPENSE 

(COUNT) - OVERHEAD. 



Unswitchinq 



Procedures may contain tests that result 
in the same action for any set of 
executions of that procedure. In such a 
case, the test can be removed from the 
procedure and the procedure duplicated. 
For example, if "SWITCH" is not changed 
within the loop, replace 



COUNT=0 
PERFORM 
TIMES. 



JOBS-TOTAL-CAL JOB-NUM 



Incorporating Procedures Inline 



Based on module size, number of 
repetitions, modification activities, 
future expansion considerations, and 
frequency statistics, small procedures can 
be moved in-line to minimize overhead 
r equi reraent s . 



Tabling 



JOB-TOTAL-CAL. 

ADD 1 TO COUNT. 



This technique is designed to replace 
many IF statements by one table look-up 
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statement, or by one computed GO TO 
statement. For example, if- the same 
data-item is tested in many successive IF 
statements to set the value of another 
data-item to some constant, and the range 
of tested values of the original data-item 
is limited, then a predetermined table of 
values could be used to assign the value of 
the second data- item. Similarly, many 
consecutive statements of the form 

IF data-ltem-l=some-constant GO TO 
some-procedure 

could be replaced by one computed GO TO 
statement. 



Efficiency Guidelines 



Based on execution frequency statistics, 
the following types of coding 
inefficiencies may be removed, 

1. Unaligned decimal places in arithmetic 
or numeric comparison operands. 

2. Different size operands in moves, 
comparisons, or arithmetic operations. 

3. Mixed usage in arithmetic or numeric 
comparison operands. 

4. Display usage in arithmetic operands 
or one numeric operand and one display 
operand in a comparison. 

5. SYNC missing for COMP or COMP-1, -2, 
or -U items. 

6. Inefficient COMP type picture; that 
is, no sign or more than 9 digits in a 
COMP item and no sign, even number of 
digits, or more than 16 digits in 
COMP- 3 items. 

7. Noncomputational subscripts. 



DIAGNOSTIC MESSAGES 



Diagnostic messages are generated by the 
compiler and listed on SYSLST when errors 
are found in the source program. 

Note : Diagnostic messages (except FIPS 
diagnostic messages) are suppressed when 
the NOERRS option is in effect. 



WORKING WITH DIAGNOSTIC MESSAGES 



Approach the diagnostic messages in 
the order in which they appear on the 
source listing. It is possible to get 
compound diagnostic messages. 
Frequently, an earlier diagnostic 
message indicates the reason for a 
later diagnostic message. For 
example, a missing quotation mark for 
an alphabetic or alphanumeric literal 
could involve the inclusion of some 
clauses not intended for that 
particular literal. This could cause 
an apparently valid clause to be 
diagnosed as invalid because it is not 
complete, or because it is in conflict 
with something that preceded it. 

Check for missing or superfluous 
punctuation, or other errors of this 
type. 

Frequently, a seemingly meaningless 
message is clarified when the valid 
syntax or format of the clause or 
statement in question is referenced. 

Statement numbers are generated when a 
verb or procedure-name is encountered. 



GENERATION OF DIAGNOSTIC MESSAGES 



The compiler scans the statement, 
element by element, to determine whether 
the words are combined in a meaningful 
manner. Based upon the elements that have 
already been scanned, there are only 
certain words or elements that can be 
correctly encountered.. 

If the anticipated elements are not 
encountered, a diagnostic message is 
produced. Some errors may not be lancovered 
until information from various sections of 
the program is combined and the 
inconsistency is noted. Errors uncovered 
in this manner can produce a slightly 
different message format than those 
uncovered when the actual source text is 
still available. The message that is made 
unique through that particular error may 
not contain, for example, the actual source 
statement that produced the error. 

Errors that appear to be identical are 
diagnosed in a slightly different manner, 
depending on where they were encountered by 
the compiler and how they fit within the 
context of valid syntax* For example^ a 
period missing from the end of the 
Working-Storage section header is diagnosed 
specifically as a period required. There 
is no other information that can appear at 
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that point. However, if at the end of a 
data item description entry, an element is 
encountered that is not valid at that 
point, such as the digits 02, it is 
diagnosed as invalid. Any clauses 
associated with the 02 entry which conflict 
with the clauses in the previous entry (the 
one that contained the missing period) , are 
diagnosed. Thus, a missing period produces 
a different type of diagnostic message in 
one situation than in the other. 

If an error occurs during compilation of 
an ON statement, the diagnostic message may 
refer to the previous statement number. 



ISln D STATEMENT OUT OF SEQUENCE. 

I 



• If a D-level diagnostic is generated 
and the error is a compiler error, the 
job will terminate via the CANCEL macro 
and produce a dump. 

• The following messages will not be 
issued during a SYNTAX-only compilation 
or during a CSYNTAX compilation if a 
C-level error in the diagnostic number 
ILAOxxx to ILAUxxx range was 
encountered: 



Notes : 



ILA5001I 



COMPILER ERROR, 
ABANDONED. 



COMPILATION 



If an E-level diagnostic is generated, 
the LINK option is cancelled, and any 
linkage editor control statements in 
the job stream are invalid. For this 
reason, the following message is issued 
by the Job Control Processor following 
the first linkage editor control 
statement encountered: 



ILA5002I COMPILER ERROR. COMPILATION 
ABANDONED, 

ILA5003I DIVISOR IS ZERO. RESULT WILL BE 
ALL 9*S. 

ILASOOai ALPHANUMERIC SENDING FIELD TOO 

BIG. 18 LOW ORDER BYTES USED. 
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ILA5005I COHPILER ERROR. COHPILATION 
ABANDONED. 



ILA5006I COMPILER ERROR. COMPILATION 
ABANDONED. 



ILA5007I COMPILER ERROR. COMPILATION 
ABANDONED. 



ILA5008I COMPILER ERROR. COMPILATION 
ABANDONED. 

ILA5009I COMPILER ERROR. COMPILATION 
ABANDONED. 

ILA5010I HIG2 ORDER TRDNCATION OF THE 
CONSTANT DID OCCUR. 

ILA5011I HIGH ORDER TRDNCATION MIGHT 
OCCUR. 

ILA5012I LOST INTERMEDIATE RESULT 

ATTRIBUTES IN 'XINTR* TABLE. 
COMPILATION ABANDONED. 

ILA5013I ILLEGAL COMPARISON OF TWO NUMERIC 
LITERALS. STATEMENT DISCARDED. 

ILA5014I KEY IN SEARCH ALL AT INVALID 

OFFSET. STATEMENT DISCARDED. 

ILA5015I INVALID USE OF SPECIAL REGISTER. 
SUBSTITUTING-TALLY . 

ILA5016I MORE THAN 255 SUBSCRIPT ADDRESS 
CELLS USED. PROGRAM CANNOT 
EXECUTE CORRECTLY. 

ILA5017I INVALID ADVANCING OPTION FOR A 
DTFCD FILE. USING STACKERI. 

ILA5018I INTEGER IN POSITIONING OPTION NOT 
BETWEEN AND 3. 1 ASSUMED. 

ILA5019I PUNCH STACKER SELECT SPECIFIED 

FOR A DTFPR FILE. USING 'SKIP 
TO CHANNEL 1». 

ILA5020I IDENTIFIER NAME (S) IN EXHIBIT 

EXCEEDS MAXIMUM. TRUNCATED TO 
120 CHARACTERS. 

ILA5021I INTEGER IN ADVANCING OR 
POSITIONING OPTION NOT 
POSITIVE. POSITIVE ASSUMED. 

ILA5022I MORE THAN 2-DIGIT INTEGER IN 
ADVANCING OPTION. USING 
INTEGER 1 . 

ILA5023I EOF INVALID FOR DOUBLE-BUFFERED 
FILE. IGNORED. 

ILA5024I END-OF-PAGE OPTION REQUESTED FOR 
NON-DTFPR FILE. IGNORED. 



ILA5025I ADVANCING OR POSITIONING OPTION 
ILLEGAL FOR NON-SEQUENTIAL 
FILE. IGNORED. 

ILA5026I EXHIBIT OPERAND GREATER THAN 256 
BYTES. LENGTH OF 256 ASSUMED. 

ILA5027I NEGATIVE OR ZERO SUBSCRIPT 

INVALID. CHANGED TO POSITIVE 
1. 

ILA5028I RESULT FIELD WILL HAVE POSITIVE 
SIGN. 

ILA5029I STOP RUN GENERATED AFTER LAST 
STATEMENT. 

ILA5030I INSTEAD OF AN HVCL INSTRUCTION, 
AN MVC OR A CALL TO AN 
OBJECT-TIME SUBROUTINE HAS BEEN 
GENERATED BECAUSE THE FIELDS 
OVERLAP DESCRUCTIVELY. 

ILA5031I AN MVCL INSTRUCTION HAS BEEN 

GENERATED FOR A HOVE INVOLVING 
AT LEAST ONE LINKAGE SECTION 
DATA-NAME. IF THE FIELDS 
OVERLAP DESTRUCTIVELY THE MOVE 
WILL NOT BE PERFORMED. 

In addition, no message of the form 
ILA6XXX will be issued. 




LINKAGE EDITOR OUTPUT 



The Linkage Editor produces 
messages, console messages, and 
map. For a complete descriptio 
and error messages from the Lin 
see the publication DOS/VS Syst 
Statements . Output resulting f 
editing of a COBOL program is d 



diagnostic 
a storage 
n of output 
kage Editor , 
em Control 



'rom the link 
iiscussed in 
the chapter "Interpreting Output." 



EXECUTION TIME MESSAGES 



When an error condition that is 
recognized by compiler-generated code 
occurs during execution, an error message 
is written on SYSLST and often SYSLOG . 

Messages that normally appear on SYSLOG 
are provided with a code indicating from 
which partition the message originated = 

A complete list of execution-time 
messages can be found in "Appendix I: 
Diagnostic Messages." 
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E ECOBDING PROGRAM STATUS 



TAKING A CHECKPOINT 



When a program is expected to run for an 
extended period of time, provision should 
be made for taking checkpoint information 
periodically during the run. A checkpoint 
is the recording of the status of a problem 
program and storage (including input/output 
status and the contents of the general 
registers) . Thus, it provides a means of 
restarting the job at an intermediate 
checkpoint position rather than at the 
beginning, if for any reason processing is 
terminated before the normal end of the 
program. For example, a job of higher 
priority may require immediate processing, 
or some malfunction (such as a. power 
failure) may occur and cause an 
interruption. Checkpoints are taken using 
the COBOL RERUN clause. 

Restart is a means of resuming the 
execution of the program from one of the 
checkpoints rather than from the beginning 
of the job. The ability to restart is 
provided through the RSTRT job control 
statement. Full details on using this 
statement are in -DOS/TS System Control 
Statements. 



RERUN CLAUSE 



The presence of the RERUN clause in the 
source program causes the CHKPT macro 
instruction to be issued at the specified 
interval. When the CHKPT macro instruction 
is issued, the following information is 
saved : 

1 . Information for the Restart and other 
supervisor or job control routines. 

2. The general registers. 

3. Bytes 8 through 10, and 12 through 45 
of the Communication Region. 

U. The problem program area. 

5. All file protection extents for files 
assigned to mass storage devices if 
the extents are attached to logical 
units contained in the program for 
which checkpoints are taken. 

Since the COBOL RERUN clause provides a 
linkage to the system CHKPT macro 
instruction, any warnings and restrictions 
on the use of this macro instruction also 
apply to the use of the RERUN clause. See 
the publication DOS/VS Supervisor and I/O 
Macros for a complete description of the 
CHKPT macro instruction. 



In order to take a checkpoint, the 
programmer must specify the source language 
RERUN clause and must define the file upon 
which checkpoint records are to be written 
(for example, ASSGN, EXTEND, etc.). Checkpoini 
information must be written on a 2311, 2314, 
2319, 3330, 3340, 3350, or fixed block mass 
storage device or on a magnetic tape — either 
7- or 9- track. Checkpoint records cannot be 
embedded in one of the problem program's 
output files, that is, the program must 
establish a separate file exclusively for 
checkpoint records. Checkpoints cannot be 
written on VSAM files. 

In designing a program for which 
checkpoints are to be taken, the programmer 
should consider the fact that, upon 
restarting, the program must be able to 
continue as though it had just reached that 
point in the program at which termination 
occurred. Hence, the programmer should 
ensure that: 

1. File handling is such as to permit 
easy reconstruction of the status of 
the system as it existed at the time 
of checkpoint was taken. For example, 
when multifile reels are used, the 
operator should be informed (by 
message) as to which file is in use at j 
the time a checkpoint is to be taken. 

He requires this information at 
restart time. 

2. The contents of files are not altered 
between the time of the checkpoint and 
the time of the restart. For 
sequential files , all records written 
on the file at the time the checkpoint 
is taken should be unaltered at 
restart time. For nonsequential 
files, care must be taken to design 
the program so that a restart will not 
duplicate work that has been completed 
between checkpoint time and restart 
time. For example, suppose that 
checkpoint 5 is taken. By adding an 
amount representing the interest due, 
account XYZ is updated on a 
direct-access file that was opened 
with the I-O option. If the program 
is restarted from checkpoint 5 and if 
the interest is recalculated and again 
added to account XYZ, incorrect 
results will be produced. 

If the program is modular in design, 
RERUN statements must be included in all 
modules that handle files for which 
checkpoints are to be taken. (When an 
entry point of a module containing a RERUN 
statement is encountered, a COBOL | 

subroutine, ILBDCKPO, is called. ILBDCKPO 1 
enters the files of the module into the 
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list of files to be repositioned.) 
Repositioning to the proper record will not 
occur for any files that were defined in 
modules other than those containing REP ON 
statements. Horeover, a restart from any 
given checkpoint may not reposition other 
tapes on which checkpoints are stored. 
Note, too, that only one disk checkpoint 
file can be used. 



RESTARTING A PROGRAM 



If the programmer requests checkpoints 
in his job by means of the COBOL RERUN 
clause, the following message is given each 
time a checkpoint is taken: 

0C001 CHKPT nnnn HAS BEEN TAKEN ON 
SYSxxx 



nnnn 



is the 4-character identification of 
the checkpoint record. 



To restart a job from a checkpoint, 
following steps are required: 



the 



Replace the // EXEC statement with a 
// RSTRT statement. The format of the 
RSTRT statement is discussed in the 



3. 



chapter "Preparing COBOL Programs For 
Processing." All other job control 
statements applicable to the job step 
should be the same as when the job was 
originally run. If necessary, the 
channel and unit addresses for the // 
ASSGN control statements may be 
changed. 

Rewind all tapes used by the program 
being restarted, and mount them on 
devices assigned to the symbolic units 
required by the program. If 
ffiultivolume files are used, mount (on 
the primary unit) the reel being used 
at the time that the checkpoint was 
taken, and rewind it. If multifile 
volumes are used, position the reel to 
the start of the file referenced at 
the time the checkpoint is being 
taken. 

Reposition any card file so that only 
cards not yet read when the checkpoint 
was taken are in the card reader. 

Execute the job. 

A checkpointed program can be 
restarted only in the same partition. 
The virtual partition must start at 
the same location as when the program 
was checkpointed and its end address 
must not be lower than at that time. 
This is because checkpoint dumps 
the entire virtual partition. 




Proqram Checkout 263 



APPENDIX A: SAMPLE PEOGEAM OUTPUT 



The following is a sample COBOL program 
and the output listing resulting from its 
compilation, link editing, and execution. 
The program creates a blocked, unlabeled, 
standard seguential file, writes it out on 
tape, and then reads it back in. It also 
does a check on the field called 
NO-OF-DEPEbDEHTS . All data records in the 
file are displayed. Those with a zero in 
the NO-OF-DEPENDENTS field are displayed 
with the special character Z. The records 



of the file are not altered from the time 
of creation, despite the fact that the 
NO-OF-DEPENDENTS field is changed for 
display purposes. The individual records 
of the file are created using the 
subscripting technique. 



The output formats illustrated in the 
listing are described in the chapter 
"Interpreting Output." 



// JOB SAMPLE 

// OPTION NODECK, LINK, LIST, LISTX,SYM, ERRS 

// EXEC FCOBOL 



1 IBM DOS VS COBOL 



REL 1.0 



PP NO. 57U6-CB1 



08.17.32 10/02/73 



CBL QUOTE, OPT 


00001 


000010 


00002 


000020 


00003 




C0004 




00005 




00006 




00007 




00008 




00009 




00010 


000100 


00011 


000110 


00012 


000120 


00013 


000130 


00014 


000140 


00015 


000150 


00016 


000160 


00017 


000170 


00018 


000180 


00019 


000190 


00020 


000200 


00021 


000210 


00022 


000220 


C0023 


000230 


00024 


000240 


00025 


000250 


00026 


000255 


00027 


000260 


00028 


000270 


00029 




00030 


000290 


00031 


000300 


00032 


000310 


00033 


000320 


00034 


000330 


00035 


000340 


00036 


000350 


00037 





,SXREF,LVL=A 

IDENTIFICATION DIVISION. 
PROGRAM-ID. TESTRUN. 

AUTHOR. PROGRAMMER NAME. , 

INSTALLATION. NEW YORK DEVELOPMENT CENTER 
DATE-WRITTEN. APRIL 18,1973 
DATE-COMPILED. 10/02/73 

REMARKS. THIS PROGRAM HAS BEEN WRITTEN AS A SAMPLE PROGRAM FOR 
COBOL USERS. IT CREATES AN OUTPUT FILE AND READS IT BACK 
AS INPUT. 

ENVIRONMENT DIVISION. 
CONFIGURATION SECTION. 
SOURCE-COMPUTER. IBM-360-H50. 
OBJECT-COMPUTER. IBM-370. 
INPUT- OUTPUT SECTION. 
FILE-CONTROL. 

SELECT FILE-1 ASSIGN TO SYS008-UT-2400-S. 

SELECT FILE-2 ASSIGN TO SYS008-UT-2400-S. 

DATA DIVISION. 
FILE SECTION, 
FD FILE-1 

LABEL RECORDS ARE OMITTED 

BLOCK CONTAINS 5 RECORDS 

RECORDING MODE IS F 

RECORD CONTAINS 20 CHARACTERS 

DATA RECORD IS RECORD-1. 
01 RECORD-1. 

05 FIELD-A PIC X(20). 
FD FILE-2 

LABEL RECORDS ARE OMITTED 

BLOCK CONTAINS 5 RECORDS 

RECORD CONTAINS 20 CHARACTERS 

RECORDING MODE IS F 

DATA RECORD IS RECORD-2. 
01 RECORD-2. 

05 FIELD-A PIC X(20). 
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Tt»M r\rte Ttq Pri^RTiT 



REL 1,0 



PP NO. 5746-CB.l 



■17.32 10/02/73 



00038 
00039 

oooao 

00041 
0OOU2 
00043 
00044 
00045 
00046 
00047 
00048 
00049 
00050 
00051 
00052 
00053 
00054 
00055 
00056 
00057 
00058 
00059 
00060 
00061 
C0062 
00063 
00064 
00065 
00066 
00067 
00068 
00069 
00070 
00071 
00072 
00073 
00074 
00075 
00076 
00077 
00078 
00079 
00080 



000370 
000380 

000400 
000410 
000420 
000430 
000440 
000450 
000460 
000470 
000480 
000490 
000500 
000510 
000520 
000530 
000540 
000550 

000570 
000580 
000590 
000600 
000610 
000620 
000630 
000640 
000650 
000660 
000670 
000680 
000690 
000700 
000710 
000720 
000730 
000740 
000750 
000760 
000770 
000780 
000790 



WORKING-STORAGE SECTION. 
01 FILLER. 

02 KOUNT PIC S99 COMP SYNC. 

ALPHABET PIC X(26) VALUE IS "ABCDEFGHIJKLMNOPQRSTUVWXYZ" , 

ALPHA REDEFINES ALPHABET PIC X OCCURS 26 TIMES. 

NUMBR PIC S99 COMP SYNC. 

DEPENDENTS PIC X(26) ^ALUE "01234012340123401234012340". 

DEPEND REDEFINES DEPENDE*1TS PIC X OCCURS 26 TIMES. 
WORK-RECORD. 
05 NAME-FIELD PIC X. 

FILLER PIC X VALUE IS SPACE. 

RECORD-NO PIC 9999. 

FILLER PIC X VALUE IS SPACE. 

LOCATION PIC AAA VALUE IS "NYC". 

FILLER PIC X VALUE IS SPACE. 

NO-OF- DEPENDENTS PIC XX. 

FILLER PIC X(7) VALUE IS SPACES. 



01 



02 
02 
02 
02 
02 



05 
05 
05 
05 
05 
05 
05 



PROCEDURE DIVISION. 
BEGIN. 

NOTE THAT THE FOLLOWING OPENS THE OUTPUT FILE TO BE CREATED 

AND INITIALIZES COUNTERS. 
STEP-1. OPEN OUTPUT FILE-1. MOVE ZERO TO KOUNT, NUMBR. 

NOTE THAT THE FOLLOWING CREATES INTERNALLY THE RECORDS TO BE 

CONTAINED IN THE FILE, WRITES THEM ON TAPE, AND DISPLAYS 

THEM ON THE CONSOLE. 
STEP- 2. ADD 1 TO KOUNT, NUMBR. MOVE ALPHA (KOUNT) TO 

NAME-FIELD. 

MOVE DEPEND (KOUNT) TO NO-OF-DEPENDENTS 

MOVE NUMBR TO RECORD-NO. 
STEP-3. DISPLAY WORK-RECORD UPON CONSOLE. WRITE RECORD-1 FROM 

WORK-RECORD. 
STEP-4. PERFORM STEP-2 THRU STEP-3 UNTIL KOUNT IS EQUAL TO 26. 

NOTE THAT THE FOLLOWING CLOSES THE OUTPUT FILE AND REOPENS 

IT AS INPUT. 
STEP- 5. CLOSE FILE-1. OPEN INPUT FILE-2. 

NOTE THAT THE FOLLOWING READS BACK THE FILE AND SINGLES 

OUT EMPLOYEES WITH NO DEPENDENTS. 
STEP- 6. READ FILE-2 RECORD INTO WORK-RECORD AT END GO TO STEP- 8. 
STEP-7. IF NO-OF-DEPENDENTS IS EQUAL TO "0" MOVE "Z" TO 

NO-OF-DEPENDENTS. EXHIBIT NAMED WORK-RECORD- GO TO STEP-6. 
STEP- 8. CLOSE FILE-2. 

STOP RUN. 
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INTiiNL NAME LVL SOURCE NAME 



REL 1.0 



PP NO. 5746-CBl 



DNM=1-1U8 


FD 


FILE-1 


DNM=1-179 


01 


RECORD- 1 


DNM=l-200 


02 


FIELB-A 


DNM=1-217 


FD 


FILE-2 


DNM=l-248 


01 


RECORD- 2 


DNM=l-269 


02 


FIELD-A 


DNM=l-289 


01 


FILLER 


DNM=l-308 


02 


KOUNT 


DNM=l-323 


02 


ALPHABET 


DNM=1-341 


02 


ALPHA 


DNM=l-359 


02 


NUMBR 


DNM=1-37U 


02 


DEPENDENTS 


DNM=l-394 


02 


DEPEND 


DNM=1-410 


01 


WORK-RECORD 


DNM=1-H34 


02 


NAME-FIELD 


DNM=1-45U 


02 


FILLER 


DNM=1-173 


02 


RECORD-NO 


DNM=l-i*92 


02 


FILLER 


DNM=2-000 


02 


LOCATION 


DNM=2-018 


02 


FILLER 


DNM=2-037 


02 


NO-OF-DEPENDENTS 


DNM=2-063 


02 


FILLER 



BASE 


DISPL 


INTRNL NAME 


DEFINITION 


USAGE 


DTF=01 




DNM=1-148 






DTFKT 


BL=1 


000 


DNK=1-179 


DS 


0CL20 


GROUP 


BL=1 


000 


DNM=l-200 


DS 


20C 


DISP 


DTF=02 




DNM=1-217 






DTFMT 


BL=2 


000 


DNM=l-248 


DS 


0CL20 


GROUP 


BL=2 


000 


DNM=l-269 


DS 


20C 


DISP 


BL=3 


000 


DNM=l-289 


DS 


0CL56 


GROUP 


BL=3 


000 


DNM=l-308 


DS 


IH 


ccmp 


BL=3 


002 


DNM=l-323 


DS 


26C 


DISP 


BL=3 


002 


DNM=1-341 


DS 


IC 


DISP 


BL=3 


OIC 


DNM=l-359 


DS 


IH 


COMP 


BL=3 


OlE 


DNM=l-374 


DS 


26C 


DISP 


BL=3 


CIE 


DNK=l-394 


r-ic 


IC 


DIS? 


BL=3 


038 


DNM=1-410 


DS 


0CL20 


GROUP 


BL=3 


038 


DNM=l-434 


DS 


IC 


DISP 


BL=3 


039 


DNM=l-454 


DS 


IC 


DISP 


BL=3 


03A 


DNM=l-473 


3S 


4C 


DISP-NK 


BL=3 


03E 


DNM=l-492 


DS 


IC 


DISP 


BL=3 


03F 


DNM=2-000 


DS 


3C 


DISP 


BL=3 


042 


DNM=2-018 


DS 


IC 


DISP 


BL=3 


043 


DNM=2-037 


DS 


2C 


DISP 


BL=3 


045 


DNM=2-063 


DS 


7C 


DISP 



08.17.32 10/02/73 

R Q M 
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MEMORY MAP 




TGT 


003F8 


SAVE AREA 


003F8 


SWITCH 


00440 


TALLY 


00444 


SORT SAVE 


00448 


ENTRY- SAVE 


0044C 


SORT CORE SIZE 


00450 


NSTD-REELS 


00454 


SORT RET 


00456 


WORKING CELLS 


00458 


SORT FILE SIZE 


00588 


SORT MODE SIZE 


0058C 


PGT-VN TBL 


00590 


TGT-VN TBL 


00594 


SORTAB ADDRESS 


00598 


LENGTH OF VN TBL 


0059C 


LNGTH OF SORTAB 


0059E 


PGM ID 


005AO 


A(INITl) 


005A8 


UPSI SWITCHES 


005AC 


DEBUG TABLE PTR 


005B4 


CURRENT PRIORITY 


005B8 


TA LENGTH 


005B9 


PRBLl CELL PTR 


005BC 


UNUSED 


005C0 


RESERVED 


005C4 


VSAM SAVE AREA ADDRESS 


005C8 


UNUSED 


005CC 


RESERVED 


005D4 


OVERFLOW CELLS 


005EC 


BL CELLS 


005EC 


DTFADR CELLS 


005F8 


FIB CELLS 


00600 


TEMP STORAGE 


00608 


TEMP STORAGE- 2 


00610 


TEMP STORAGE- 3 


00610 


TEMP STORAGE- 4 


00610 


BLL CELLS 


00610 


VLC CELLS 


00614 


SBL CELLS 


00614 


INDEX CF;T,T,S 


00614 


SUBADR CELLS 


00614 


ONCTL CKT.T.R 


0061C 


PFMCTL CELLS 


0061C 


PFMSAV CELLS 


0061C 


VN CELLS 


00620 


SAVE AREA =2 


00624 


XSASW CELLS 


00624 


XSA CELLS 


00624 


PARAK CELLS 


00624 


RPTSAV AREA 


00628 


CHECKPT CTR 


00628 


lOPTR CELLS 


00628 


DEBUG TABLE 


00628 
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REL 1.0 



PP NO. 5746-CBl 



08.17.32 10/02/73 



LITEEAL POOL (HEX) 



006H0 (LIT+0) 00000001 
00658 (LIT+24) C2C6C3DU 



001A5B5B 
E4D35B5B 



C2D6D7C5 
COOOOOOO 



D5405B5B C2C3D3D6 E2C55B5B 



DISPLAY LITERALS (BCD) 
00 664 (LTL+36) 'WORK- RECORD' 



PGT 

DEBUG LINKAGE AREA 
OVERFLOW CELLS 
VIRTUAL CELLS 
PROCEDURE NAME CELLS 
GENERATED NAME CELLS 
SUBDTF ADDRESS CELLS 
VNI CELLS 
LITERALS 
DISPLAY LITERALS 
PROCEDURE BLOCK CELLS 



00628 

00628 
00628 
0062C 
00638 
00638 
0063C 
0063C 
00640 
00664 
00670 



REGISTER ASSIGNMENT 



REG 6 


BL =3 


REG 7 


BL =1 


REG 8 


BL =2 



WORKING-STORAGE STARTS AT LOCATION 00100 FOR A LENGTH OF 00050. 
PROCEDURE BLOCK ASSIGNMENT 
PBL = REG 11 
PBL =1 STARTS AT LOCATION 000674 STATEMENT 60 
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57 



60 
60 



64 
6H 



bH 



67 



000674 



000674 



000674 










000674 


58 


BO 


C 


048 


000678 


58 


20 


D 


1F4 


00067C 


41 


10 


C 


OlE 


000680 


58 


00 


D 


200 


000684 


18 


40 






000686 


05 


FO 






000688 


50 


00 


F 


008 


00068C 


45 


00 


F 


OOC 


000690 


OOCOOOOO 


000694 


OA 


02 






000696 


41 


00 


D 


200 


00069A 


58 


FO 


C 


008 


00069E 


05 


EF 






0006A0 


58 


10 


D 


200 


0006A4 


96 


10 


1 


020 


0006A8 


50 


20 


D 


1F4 


0006AC 


58 


70 


D 


1F4 


0006B0 


D2 


01 


6 


000 C 018 


0006B6 


D2 


01 


6 


OIC C 018 


0006BC 










0006BC 


48 


30 


C 


OlA 


0006C0 


4A 


30 


6 


000 


0006C4 


4E 


30 


D 


210 


0006C8 


D7 


05 


D 


210 D 210 


0006CE 


94 


OF 


D 


216 


0006D2 


4F 


30 


D 


210 


0006D6 


40 


30 


6 


000 


0006DA 


48 


30 


C 


OlA 


0006DE 


4A 


30 


6 


OIC 


0006E2 


4E 


30 


D 


210 


0006E6 


D7 


05 


D 


210 D 210 


0006EC 


94 


OF 


D 


216 


0006FO 


4F 


30 


D 


210 


0006F4 


40 


30 


6 


OIC 


0006F8 


41 


40 


6 


002 


0006FC 


48 


20 


6 


000 


000700 


4C 


20 


C 


OlA 


000704 


lA 


42 






000706 


5B 


40 


C 


018 


00070A 


50 


40 


D 


21C 


00070E 


58 


EO 


D 


21C 


000712 


D2 


00 


6 


038 E 000 


000718 


41 


40 


6 


OlE 


00071C 


48 


20 


6 


000 


000720 


4C 


20 


C 


OlA 


000724 


lA 


42 






000726 


5B 


40 


C 


018 


00072A 


50 


40 


D 


220 


00072E 


58 


FO 


D 


220 


000732 


D2 


00 


6 


043 F 000 


000738 


92 


40 


6 


044 


00073C 


48 


30 


6 


OIC 


000740 


4£ 


30 


D 


210 


000744 


F3 


31 


6 


03A D 216 


00074A 


96 


FO 


6 


03D 



PN=03 



START 



PN=04 



EQU 
EQU 



EQU 


* 






L 


11,048(0,12) 


PBL=1 




L 


2,1F4(0,13) 


BL =1 




LA 


1,01E(0,12) 


LIT+6 




L 


0,200(0,13) 


DTF=1 




LR 


4,0 






BALR 


15,0 






ST 


0,008(0,15) 






BAL 


0,00C(0,15) 






DC 


X'OOOOOOOO' 






SVC 


2 






LA 


0,200(0,13) 


DTF=1 




L 


15,008(0,12) 


V(ILEDIMLO) 




BALR 


14,15 






L 


1,200(0,13) 


DTF=1 




01 


020(1), X'lO' 






ST 


2,1F4(0,13) 


BL =1 




L 


7,1F4(0,13) 


BL =1 




MVC 


000(2, 6), 018(12) 


DNM=l-308 


LIT+0 


MVC 


01C(2, 6), 018(12) 


DNM=l-359 


LIT+0 



EQU 



LH 


3,01A(0,12) 


LIT+2 




AH 


3,000(0,6) 


Di4M=l-308 




CVD 


3,210(0,13) 


TS=01 




XC 


210(6, 13), 210(13) 


TS=01 


TS=01 


NI 


216(13), X'Of 


TS=01+6 




CVB 


3,210(0,13) 


TS=01 




STH 


3,000(0,6) 


DNM=l-308 




LH 


3, OlA (0,12) 


LIT+2 




AH 


3,01C(0,6) 


DN^5=l-359 




CVD 


3,210(0,13) 


as=oi 




XC 


210(6, 13), 210(13) 


TS=01 


TS=01 


NI 


216(13), X'OF" 


15=01+6 




CVB 


3,210(0,13) 


TS=01 




STH 


3,01C(0,6) 


DNM=l-359 




LA 


4,002(0,6) 


DNM=1-341 




LH 


2,000(0,6) 


DNM=l-308 




MH 


2,01A(0,12) 


LIT+2 




AR 


4,2 






S 


4,018(0,12) 


LIT+0 




ST 


4,21C(0,13) 


SBS=1 




L 


14,21C(0,13) 


SES=1 




MVC 


038(1, 6), 000(14) 


DNM=l-434 


DNM=1-341 


LA 


4, OlE (0,6) 


DNM=l-394 




LH 


2,000(0,6) 


DNM=l-308 




MH 


2,01A(0,12) 


LIT+2 




AR 


4,2 






S 


4,018(0,12) 


LIT+0 




ST 


4,220(0,13) 


SES=2 




L 


15,220(0,13) 


SBS=2 




MVC 


043(1, 6), 000(15) 


DNM=2-37 


DNM= 1-394 


MVI 


044(6), X'40' 


DNM=2-37+l 




LH 


3,01C(0,6) 


DNM=l-359 




CVD 


3,210(0,13) 


TS=01 




UNPK 


03A(4,6),216(2,13) 


DNM=l-473 


TS=07 


01 


03D(6),X'F0' 


DNM=l-47 3+3 
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68 

68 



0C074E 



PN=05 



EQU 



68 



70 
70 



73 
73 



00074E 


58 


FO 


c 


OOC 


000752 


05 


IF 






000754 


0002 






000756 


00 








000757 


000014 




00075A 


ODOOOIFC 


00075E 


0038 






000760 


FFFF 






000762 


D2 


13 


7 


000 


000768 


58 


10 


D 


200 


00076C 


18 


41 






00076E 


58 


FO 


1 


010 


000772 


45 


BO 


F 


OOC 


000776 


50 


20 


D 


1F4 


00077a 


58 


70 


D 


1F4 


00077E 


58 


10 


D 


228 


000782 


07 


Fl 






000784 










000784 


D2 


03 


D 


224 


00078A 


41 


00 


B 


HE 


00078E 


50 


00 


D 


228 


000792 










000792 


48 


30 


6 


000 


000796 


49 


30 


C 


OIC 


00079A 


47 


80 


B 


12E 


00079E 


47 


FO 


B 


048 


0007A2 










0007A2 


D2 


03 


D 


228 


0007A8 










0007A8 


58 


10 


D 


200 


0007AC 


94 


EF 


1 


020 


0007B0 


18 


01 






0007B2 


18 


40 






0007B4 


41 


10 


C 


026 


0007B8 


07 


00 






0007BA 


05 


FO 






0007BC 


50 


00 


F 


008 


0007CO 


45 


00 


F 


OOC 


0007C4 


00000000 


0007C8 


OA 


02 






0007CA 


58 


00 


D 


200 


0007CE 


41 


10 


C 


02E 


0007D2 


OA 


02 






0007D4 


41 


10 


C 


OlE 


0007D8 


58 


00 


D 


204 


0007DC 


18 


40 






0007DE 


05 


FO 






0007E0 


50 


00 


F 


008 


0007E4 


45 


00 


F 


OOC 


0007E8 


00000000 


0007EC 


OA 


02 






0007EE 


41 


00 


D 


204 


0007F2 


58 


FO 


C 


008 


0007F6 


05 


EF 






0007F8 


58 


10 


D 


204 


0007FC 


96 


10 


1 


020 



6 038 



D 228 



PN=06 



GN=01 



GN=02 



PN=07 



L 


15,00C(0,12) 


BALR 


1,15 


DC 


X'0002' 


DC 


X'OO" 


DC 


X'000014' 


DC 


X' ODOOOIFC 


DC 


X'0038' 


DC 


X'FFFF' 



KVC 000(20, 7), 038(6) 

L 1,200(0,13) 

LR 4,1 

L 15,010(0,1) 

BAL 14, OOC (0,15) 

ST 2,1F4(0,13) 

L 7,1F4(0,13) 

L 1,228(0,13) 

BCR 15,1 

EQU * 



EQU 



V(ILEDDSPO) 



BL =3 



D«M=1-17 9 

D'rF=i 



BL =1 
BL =1 
VN=01 



mc 


224(4, 13), 228(13) 


PSV=1 


LA 


0,11E(0,11) 


GN=01 


ST 


0,228(0,13) 


VN=01 


EQU 
LH 


* 
3,000(0,6) 


DnM=l-30: 


CH 


3,01C(0,12) 


LIT+4 


BC 


8,12E(0,11) 


GN=02 


BC 


15,048(0,11) 


FN=04 


EQU 
MVC 


* 

228(4, 13), 224(13) 


V]^=01 



L 


1,200(0,13) 


DTF=1 


NX 


020(1) ,X'EF' 




LR 


0,1 




LR 


4,0 




LA 


1,026(0,12) 


LIT+14 


BCR 


0,0 




BALR 


15,0 




ST 


0,008(0,15) 




BAL 


0,00C(0,15) 




DC 


X'OOCOOOOO' 




SVC 


2 




L 


0,200(0,13) 


DTF=1 


LA 


1,02E(0,12) 


LIT+22 


SVC 


2 




LA 


1,01E(0,12) 


LIT+6 


L 


0,204(0,13) 


DTF=2 


LR 


4,0 




BALR 


15,0 




ST 


0,008(0,15) 




BAL 


0,00C(0,15) 




DC 


X'OOOOOOOO' 




SVC 


2 




LA 


0,204(0,13) 


DTF=2 


L 


15,008(0,12) 


V(ILBDIMLO) 


BALR 


14,15 




L 


1,204(0,13) 


DTF=2 


01 


020(1), X'lO* 





DWK=1-410 



VN=01 



PSV=1 
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76 
76 



76 

77 
77 

77 



78 
79 
79 



80 



000800 










000800 


58 


10 


D 


204 


000804 


91 


20 


1 


010 


000808 


47 


10 


B 


IBE 


00080C 


18 


41 






00080E 


41 


FO 


C 


010 


000812 


D2 


02 


1 


025 


000818 


58 


FO 


1 


010 


00081C 


45 


EO 


F 


008 


000820 


50 


20 


D 


1F8 


000824 


58 


80 


D 


1F8 


000828 


D2 


13 


6 


038 


00082E 


47 


FO 


B 


1C2 


000832 










000832 


47 


FO 


B 


208 


000836 










000836 










000836 


95 


FO 


6 


043 


00083A 


47 


70 


B 


IDA 


00083E 


95 


40 


6 


044 


000842 


47 


70 


B 


IDA 


000846 


92 


E9 


6 


043 


00084A 


92 


40 


6 


044 


00084E 










00084E 


58 


10 


C 


038 


000852 


50 


10 


D 


22C 


000856 


41 


20 


D 


22C 


00085A 


58 


FO 


C 


OOC 


00085E 


05 


IF 






000860 


8001 






000862 


10 








000863 


OOOOOB 




000866 


0C00003C 


00086A 


0000 






00086C 


00 








00086D 


000014 




000870 


ODOOOIFC 


000874 


0038 






000876 


FFFF 






000876 


47 


FO 


B 


18C 


00087C 










00087C 


58 


10 


D 


204 


000880 


94 


EF 


1 


020 


000884 


18 


01 






000886 


18 


40 






000888 


41 


10 


C 


026 


00088C 


07 


00 






00088E 


05 


FO 






000890 


50 


00 


F 


008 


000894 


45 


00 


F 


OOC 


000898 


00000000 


00089C 


OA 


02 






00089E 


58 


00 


D 


204 


0008A2 


41 


10 


C 


02E 


0008A6 


OA 


02 






0008A8 


OA 


OE 







EQU 



F 001 



8 000 



L 


1,204(0,13) 


DTF=2 


TM 


010(1), X"20' 




EC 


1,1BE(0,11) 


GN=03 


LR 


4,1 




LA 


15,010(0,12) 


GiN=03 


MVC 


025(3,1), 001(15) 




L 


15,010(0,1) 




BAL 


14,008(0,15) 




ST 


2,1F8(0,13) 


BL =2 


L 


8,1F8{0,13) 


BL =2 


MVC 


038(20, 6), 000(8) 


DNM=1-410 


BC 


15,1C2(0,11) 


GN=04 


EQU 


♦ 




BC 


15,208(0,11) 


PN=010 


EQU 


* 





EQU 



15,18C(0,11) 



PN=010 EQU 


* 


L 


1,204(0,13) 


NI 


020(1), X'EF' 


LR 


0,1 


LR 


4,0 


LA 


1,026(0,12) 


BCR 


0,0 


BALR 


15,0 


ST 


0,008(0,15) 


BAL 


0,00C(0,15) 


DC 


X'OOOOOOOO' 


SVC 


2 


L 


0,204(0,13) 


LA 


1,02E(0,12) 


SVC 


2 



DNM=l-248 



CLI 


043(6) ,X"FO' 


DNM=2-37 


BC 


7,1DA(0,11) 


GN=05 


CLI 


044(6), X'40' 


DNM=2-37+l 


BC 


7,1DA(0,11) 


GN=05 


MVI 


043(6), X'E9' 


DNM=2-37 


MVI 


044(6), X'40' 


DNiyi=2-37+l 


EQU 


* 




L 


1,038(0,12) 


LIT+32 


ST 


1,22C(0,13) 


PRM=1 


LA 


2,22C(0,13) 


PRM=1 


L 


15,00C(0,12) 


V(ILBDDSPO) 


BALR 


1,15 




DC 


X'8001' 




DC 


X'lO' 




DC 


X'OOOOOB' 




DC 


X'OC00003C' 


LIT+36 


DC 


X'OOOO' 




DC 


X'OO' 




DC 


X'000014' 




DC 


X 'ODOOOIFC ■ 


BL =3 


DC 


X'0038' 




DC 


X'FFFF' 





FN=08 



DTF=2 



LIT+14 



DTF=2 
LIT+22 



14 
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0008AA 


50 


DO 


5 


008 


0008AE 


50 


50 


D 


004 


0008B2 


58 


20 


C 


004 


0008B6 


95 


00 


2 


000 


OOOSBA 


07 


79 






0008BC 


92 


FF 


2 


000 


0008C0 


96 


10 


D 


048 


0008Cit 


50 


EO 


D 


054 


0008C8 


05 


FO 






0008CA 


91 


20 


D 


048 


0008CE 


47 


EO 


F 


016 


0008D2 


58 


00 


B 


048 


0008D6 


98 


2D 


B 


050 


0008DA 


58 


EO 


D 


054 


C008DE 


07 


FE 






0008E0 


96 


20 


D 


048 


0008E4 


41 


60 





004 


0008E8 


41 


10 


C 


000 


0008EC 


41 


70 


C 


003 


0008F0 


05 


50 






0008F2 


58 


40 


1 


000 


0008F6 


IE 


4E 






0008F8 


50 


40 


1 


000 


0008FC 


87 


16 


5 


000 


000900 


41 


10 


C 


010 


000904 


41 


70 


C 


017 


000908 


05 


50 






00090A 


58 


40 


1 


000 


00090E 


IE 


4B 






000910 


50 


40 


1 


000 


000914 


87 


16 


5 


000 


000918 


41 


80 


D 


1F4 


00091C 


41 


70 


D 


20F 


000920 


05 


10 






000922 


58 


00 


8 


000 


000926 


IE 


OB 






00C928 


50 


00 


8 


000 


00092C 


87 


86 


1 


000 


000930 


58 


60 


D 


IFC 


000934 


58 


70 


D 


1F4 


000938 


58 


80 


D 


1F8 


00093C 


D2 


03 


D 


228 


000942 


58 


EO 


D 


IBO 


000946 


90 


6D 


E 


060 


00094A 


58 


EO 


D 


054 


00094E 


07 


FE 






000000 


05 


FO 






000002 


07 


00 






000004 


90 


OE 


F 


OOA 


000008 


47 


FO 


F 


082 


OOOOOC 


00000000 


000084 


58 


CO 


F 


0C6 


000088 


58 


EO 


C 


004 


00008C 


58 


DO 


F 


OCA 


000090 


95 


00 


E 


000 


000094 


47 


70 


F 


0A2 


000098 


96 


10 


D 


048 


00009C 


92 


FF 


E 


000 


OOOOAO 


47 


FO 


F 


OAC 



INIT2 



INI'13 



C 014 



INITl 



ST 


13,008(0,5) 




ST 


5,004(0,13) 




L 


2,004(0,12) 


VIR=1 


CLI 


000(2), X'OO" 




BC8 


7,9 




MVI 


000(2) ,X'FF' 




01 


048(13), X'lO' 


SWT+0 


ST 


14,054(0,13) 




BALR 


15,0 




TM 


048(13), X'20' 


SWT+0 


EC 


14,016(0,15) 




L 


0,048(0,11) 




LM 


2,13,050(11) 




L 


14,054(0,13) 




BCR 


15,14 




01 


048(13), X'20' 


SWT+C 


LA 


6,004(0,0) 




LA 


1,000(0,12) 




LA 


7,003(0,12) 


VIR=1-1 


BALR 


5,0 




L 


4,000(0,1) 




ALR 


4,11 




ST 


4,000(0,1) 




BXLE 


1,6,000(5) 




LA 


1,010(0,12) 


PN=01 


LA 


7,017(0,12) 


LIT+0-1 


BALR 


5,0 




L 


4,000(0,1) 




ALR 


4,11 




ST 


4,000(0,1) 




BXLE 


1,6,000(5) 




LA 


S,1F4(0,13) 


0VF=1 


LA 


7,20F(0,13) 


TS=01-1 


BALR 


1,0 




L 


0,000(0,8) 




ALR 


0,11 




ST 


0,000(0,8) 




BXLE 


8,6,000(1) 




L 


6,1FC(0,13) 


BL =3 


L 


7,1F4(0,13) 


BL =1 


L 


8,1F8(0,13) 


BL =2 


MVC 


228(4, 13), 014(12) 


VN=01 


L 


14,1B0(0,13) 




STM . 


6,13,060(14) 




L 


14,054(0,13) 




BCR 


15,14 




BALR 


15,0 




BCR 


0,0 




STM 


0,14,00A(15) 




BC 


15,082(0,15) 




DC 


30F'0' 




L 


12,0C6(0,15) 




L 


14,004(0,12) 


VIR=1 


L 


13,0CA(0,15) 




CLI 


000(14), X'OO' 




BC 


7,0A2(0,15) 




01 


048(13), X'lO' 


SWT+0 


MVI 


000(14), X'FF' 




BC 


15,0AC(0,15) 
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OOOOAi* 


98 CE F 03A 


0000A8 


90 EC D OOC 


OOOOAC 


18 5D 


OOOOAE 


98 9F F OBA 


0000B2 


91 10 D 048 


OO0OB6 


07 19 


0000B8 


07 FF 


OOOOBA 


07 00 


OOOOBC 


000008C1* 


OOOOCO 


00000000 


O0OOC4 


00000000 


0000C8 


00000628 


GOOOCC 


000003F8 


OOOODO 


00000674 


0000D4 


000008AA 


0000D8 


C3D6C2D6F3F0F0F0 


OOOOEO 


E3C5E2E3D9E4D540 


0000E8 


00000000 


OOOOEC 


F1F061F0F261F7F3 


0000F4 


F0F84BF1F74BF3F2 



LM 


12,14,03A(15) 


STM 


14,12,000(13) 


LR 


5,13 


LM 


9,lb,0EA(15) 


T.M 


048(13), X'lO' 


BCR 


1,9 


BCR 


15,15 


BCR 


0,0 


ADCON 


L4(INIT3) 


ADCON 


L4(INIT1) 


ADCON 


L4(INIT1) 


ADCON 


L4(PGT) 


ADCON 


L4CrGT) 


ADCON 


L4 (START) 


ADCON 


L4(INIT2) 


DC 


X'C3D6C2D6F3F0F0F0 


DC 


X'E3C5E2E3D9E4D540 


DC 


X'OOOOOOOO" 


DC 


X'F1F061F0F261F7F3 


DC 


X'F0F84BF1F7 4BF3F2 



SWT+0 



♦STATISTICS* 
♦STATISTICS* 
♦OPTIONS IN EFFECT* 
♦OPTIONS IN EFFECT* 
♦OPTIONS IN EFFECT^ 
♦OPTIONS IN EFFECT^ 



SOURCE RECORDS = 80 

PARTITION SIZE = 655176 

PMAP RELOC ADR = NONE 

LISTX QUOTE 

NOCLIST FLAGW 

NOSTATE TRUNC 



DATA ITEMS = 


22 


NO OF 


VERBS = 


28 




LINE COUNT = 


56 


BUFFER 


SIZE = 


512 




SPACING 


1 


FLOW 


= 


NONE 




SYM NOCATALR 




LIST 


LI.IK 


NOSTXIT 


NOLIB 


ZWB NOSUPMAP 




XREF 


ERRS 


SXRLF 


OPT 


SEQ NOSYMDMP 




NODECK 


HOVERB 


NOSYNTAX 


LVL=A 
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CKOSS-HEFERErtCE DICTIONARY 



DATA NA:>!ES 



DEFN 



REFERENCE 



ALPHA 

ALPHABET 

DEPEND 

DEPENDENTS 

flELD-A 

FIELD-A 

FILE-1 

FILE- 2 

KCUNT 

LOCATION 

NAME-FIELD 

NC-CF-DEPENDENTS 

MUMBH 

RECORD-NO 

RECORD-1 

RECORD- 2 

WORK-RECORD 



000042 
000041 
000045 
000044 
000023 
000037 
000017 
000018 
000040 
000051 
000047 
000053 
000043 
000049 
000028 
000036 
000046 



000064 



000066 



000060 
000073 
000060 

000064 
000066 
000060 
000067 
000068 
000076 
000068 



000068 
000076 
000064 



000077 
000064 



000073 
000079 
000066 



000067 



000070 



000076 000078 



PROCEDURE NAMES 



REFERENCE 



BEGIN 
STEP-1 
STEP-2 
STEP- 3 
STEP- 4 
STEP- 5 
STEP- 6 
STEP-7 
STEP-8 



000057 
000060 
000064 
000068 
000070 
000073 
000076 
000077 
000079 



000070 
000070 



000078 



000076 



ERROR MESSAGE 



00064 
00064 



ILA5011I-W 
ILA5011I-W 



HIGH ORDER TRUNCATION MIGHT OCCUR. 
HIGH ORDER TRUNCATION MIGHT OCCUR - 



FEDERAL INFORMATION PROCESSING STANDARDS (FIPS) DIAGNOSTIC MESSAGES 



LINE NUMBER 



MESSAGE 



C0006 ILA8003I-W DATE-COMPILED PARAGRAPH IS AN EXTENSION TO FIPS LEVEL A. 

00025 ILA8002I-W RECORDING MODE IS CLAUSE IS AN EXTENSION TO ALL FIPS LEVELS. 

00034 ILA8002I-W RECORDING MODE IS CLAUSE IS AN EXTENSION TO ALL FIPS LEVELS. 

00054 ILA8003I-W SPACES IS AN EXTENSION TO FIPS LEVEL A. 

00060 ILA8003I-W COMMA OR SEMICOLON AS PUNCTUATION IS AN EXTENSION TO FIPS LEVEL A. 

00062 ILA8003I-W COMMA OR SEMICOLON AS PUNCTUATION IS AN EXTENSION TO FIPS LEVEL A- 

00062 ILA8003I-W COMMA OR SEMICOLON AS PUNCTUATION IS AN EXTENSION TO FIPS LEVEL A. 

C0064 ILA8003I-W COMMA OR SEMICOLON AS PUNCTUATION IS AN EXTENSION TO FIPS LEVEL A. 

00064 ILA8003I-W MULTIPLE RESULTS IN ADD STATEMENT IS AN EXTENSION TO FIPS LEVEL A. 

00068 ILA8003I-W UPON OPTION OF DISPLAY STATEMENT IS AN EXTENSION TO FIPS LEVEL A. 

00068 ILA8002I-W UPON CONSOLE OPTION OF DISPLAY STATEMENT IS AN EXTENSION TO ALL LEVELS. 

00068 ILA8003I-W FROM OPTION OF WRITE STATEMENT IS AH EXTENSION TO FIPS LEVEL A. 

00070 ILA8003I-W UNTIL OPTION OF PERFORM STATEMENT IS AN EXTENSION TO FIPS LEVEL A. 

00076 ILA8003I-W INTO OPTION OF READ STATEMENT IS AN EXTENSION TO FIPS LEVEL A. 

00078 ILA8002I-W EXHIBIT STATEMENT IS AN EXTENSION TO ALL FIPS LEVELS. 

END OF COMPILATION 
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// EXEC LNKEDT 



JOE SAMPLE 



DOS LINKAGE EDITOR DIAGNOSTIC OF IimPUT 



ACTION TAKEN MAP REL 

LIST AUTOLINK IJFFBZZN 

LIST AUTOLINK ILBDDSPO 

LIST AUTOLINK IJJCPDV 

LIST AUTOLINK ILBDDSSO 

LIST INCLUDE IJJCPDV 

LIST AUTOLINK ILBDIMLO 

LIST AUTOLINK ILBDMNSO 

LIST AUTOLINK ILBDSAEO 

LIST ENTRY 



10/02/73 PHASE XFR-AD LOCORE HICORE DSK-AD 

PHASE*** 07D878 07D878 07F1FF 05F OF 4 



ESD TYPE LABEL 
CSECT TESTRUN 



LOADED REL-FB 

07D878 07D878 RELOCATABLE 



CSECT IJFFBZZN 07E1C8 C7i:,lC8 

♦ ENTRY IJFFZZZN 07E1C8 

♦ ?;NTRY IJFFBZZZ 07E1C8 

♦ ENTRY IJFFZZZZ 07E1C8 



CSECT ILBDSAEO 07F078 
ENTRY ILBDSAEl 07FOCO 



07F078 



♦ UNREFERENCED SYMBOLS 



002 UNRESOLVED ADDRESS CONSTANTS 



CSECT 


ILBDMNSO 


07F070 


07F070 


CSECT 


ILBDIMLO 


07F018 


07F018 


CSECT 


ILBDDSPO 


07E578 


07E578 


ENTRY 


ILBDDSPl 


07E978 




CSECT 


ILBDDSSO 


07ECF0 


07ECF0 


ENTRY 


ILBDDSSl 


07EF50 




ENTRY 


ILBDDSS2 


07EF48 




ENTRY 


ILBDDSS3 


07F008 




ENTRY 


ILBDDSSt 


07ED16 




ENTRY 


ILBDDSS5 


07EDC2 




ENTRY 


ILBDDSS6 


07EE22 




ENTRY 


ILBDDSS7 


07EDEC 




ENTRY 


ILBDDSS8 


07ED46 




CSECT 


IJJCPDV 


07EAA8 


07LAA8 


ENTRY 


UJCiiL-Vl 


07EAA8 




♦ ENTRY 


IJJCPDV2 


07EAA8 




WXTRN 


STXITPSW 






WXTRN 


ILEDDBG2 
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// ASSGN 
// EXiC 



SYS008,X*483' 



WCSK- 
WOHK- 
WORK- 
WCBK- 
WORK- 
WORK- 
«OBK- 
WORK- 
WORK- 
WCRK- 
WORK- 
WCRK- 
WCRK- 
WOKK- 
WORK- 
WCFK- 
WOBK- 
WCRK- 
WORK- 
WCBK- 
WORK- 
WORK- 
WORK- 
WCFK- 
WORK- 
WORK- 



-RECCBD 
-RECORD 
-RECORD 
-RECORD 
-RECORD 
-RECORD 
-RECORD 
-RECORD 
-RECORD 
-RECORD 
-RECORD 
-RECORD 
-RECORD 
-RECORD 
-RECORD 
-RECORD 
-RECORD 
-RECORD 
-RECORD 
-RECORD 
-RECORD 
-RECORD 
-RECORD 
-RECORD 
-RECORD 
-RECORD 



A 0001 
B 0002 
C 0003 
D 0004 
E 0005 
F 0006 
G 0007 
H 0008 
I 0009 
J 0010 
K 0011 
L 0012 
M 0013 
N 0014 
O 0015 
P 0016 
Q 0017 
R 0018 
S 0019 
T 0020 
U 0C21 

V 0022 
W 0023 
X 0024 

Y 0025 
Z 0026 



NYC 
NYC 
NYC 
NYC 
NYC 
NYC 
NYC 
NYC 
NYC 
NYC 
NYC 
NYC 
NYC 
KYC 
NYC 
NYC 
NYC 
NYC 
NYC 
NYC 
NYC 
NYC 
NYC 
NYC 
NYC 
NYC 



ECJ SAMPLE 




BG \ 




BG A 0001 NYC \ 




BG B 0002 NYC 1 




BG C 0003 NYC 2 




BG D 0004 NYC 3 




BG E 0005 NYC 4 




BG F 0006 NYC 




BG G 0007 NYC 1 




BG H 0008 NYC 2 




BG I 0009 NYC 3 




BG J 0010 NYC 4 
BG K 0011 NYC 




, 


BG L 0012 NYC 1 


\ 


BG M 0013 NYC 2 


) 


BG N 0014 NYC 3 


/ 


BG 0015 NYC 4 




BG P 0016 NYC 




BG Q 0017 NYC 1 




BG R 0018 NYC 2 




BG S 0019 NYC 3 




BG T 0020 NYC 4 




BG U 0021 NYC 




BG V 0022 NYC 1 




6G W 0023 NYC 2 




BG X 0024 NYC 3 




BG Y 0025 NYC 4 


/ 


BG Z 0026 NYC / 


1 


BG EOJ SAMPLE 




00.56. 19, DURATION 00.03.4 


2 



® 
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Fil« 



1 




Numbar 
j 








































































































































Li 




3 
Fit* WMi»!f;«r 


4 
FlU 
Swlol 


5 

Velum* 

Sa^uane* 

NumMr 


6 

f;i« 

Saquanc* 
Nuii4Mr 


11 

oz 


9 


9 

Ciaolion 
Dot* 


10 


]i 


)2 
Week 


13 
SyMwaCod* 


14 

RaMTvarf 


'• 




n 


I 


•n 


. 


. 




. 




_ 


. 


. 


. 


. 




- 


. 




5 


a 


. 


. 


. 


^ 


Oi 






S 


A 


_ 


. 


» 


n 


. 


. 


^ 


± 


9 


- 


. 


. 


. 


» 


9 


. 


. 


. 


. 


32 


« 


. 


. 


. 


. 


s 


3 


_ 


. 


. 


. 


. 


. 


. 


. 


. 


. 


. 


R 


i! 


. 


IIIM 



Man»ifiar 



Vanien 

Nwmbaraf 

C#nvrdlion 



Fila 
Saewrity 



The Standard tape file label format and contents are as follows: 



Field Name and Length 



1. 



2. 



3. 



LABEL IDENTIFIER 
3 bytes, EBCDIC 



FILE LABEL NUHBER 
1 byte, EBCDIC 

FILE IDENTIFIER 
17 bytes, EBCDIC 



FILE SERIAL NDMEER 
6 bytes, EBCDIC 



5. 


70LDHE SEODENCE 




NUMBER 




4 bytes 


6. 


FILE SEOOENCE 




4 bytes 


7. 


GENERATION TIME 




4 bytes 


8. 


VERSION NOMBBR OF 




GENERATION 




2 bytes 



Description 

Identifies the type of label. 
HDR = Header (beginning of a data file) 
EOF = End-of-file (end of a set of data) 
EOT = End-of-volume (end of the physical reel) 

Always a 1. 



Dniquely identifies the entire file, may contain 
only printable characters. Some other systems 
will not accept embedded blanks in the file 
identifier. 

Dniquely identifies a file/volume relationship. 
This field is identical to the volume serial 
number in the volume label of the first or only 
volume of a multivolume file or a multifile set. 
This field will normally be numeric (000001 to 
999999) , but may contain any six alphanumeric 
characters. 

Indicates the order of a volume in a given file or 
multifile set. The first must be numbered 0001, 
and subsequent numbers must be in proper numeric 
sequence. 

Assigns numeric sequence to a file within a multi- 
file set. The first must be numbered 0001. 

Uniquely identifies the various editions of the 
file. May be from 0001 to 9999 in proper numeric 
sequence. 

Indicates the version of a generation of a file. 
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Field Name and Length 

9. CREATION DATE 
6 bytes 



Description 

Indicates the year and the day of the year that the 
file was created. 



Position 


Code 


Meaning 


1 


blank 


none 


2-3 


00-99 


year 


4-6 


001-366 


day of year 



10, 



11. 



12 



EXPIRATION DATE 
5 bytes 



FILE SECURITY 
1 byte 



BLOCK COUNT 
6 bytes 



(e.g., January 31, 1973 would be entered as 
73031) . 

Indicates the year and the day of the year when the 
file may become a scratch tape. The format of 
this field is identical to field 9. On a 
multifile reel processed sequentially, all files 
are considered to expire on the same day. 

Indicates security status of the file. 

= No security protection. 

1 = Security protection. Additional 

identification of the file is required before 
it can be processed. 

Indicates the number of data blocks written in the 
file from the last header label to the first 
trailer label, exclusive of tapemarks . Count 
does not include checkpoint records. This field 
is used in trailer labels. 



13, 



14 



SYSTEM CODE 
13 bytes 

RESERVED 
7 bytes 



Uniquely identifies the operating system. 



Reserved. Should be recorded as blanks. 
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CnaMon Daf«— • ExpiroHon Spore 



2 



Oat* 



"L 



Fil« Nomt 




File 

Serial 

Number 










- 




Syifem Code 


- 






J 


























J 


J 










_ 


















: 


y 


J 


■ 
J 






J 












9 
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Format 1: This format is common to all data files on disk. 



Field Name and Length 

1. FILE NAME 

44 bytes, alphanumeric EBCDIC 



Description 

This field serves as the key portion of the file 
label. It can consist of three sections: 

1. File ID is an alphanumeric field assigned by 
the programmer and identifies the file. It 
can be 1 through 35 bytes in length if 
generation and version numbers are used, or 1 
through 44 bytes in length if they are not 
used . 

2. Generation Number . If used, this field is 
separated from File ID by a period. It has 
the format Gnnnn, where G identifies the 
field as the generation number and nnnn (in 
decimal) identifies the generation of the 
file. 

3. Version Number of Generation . If used, this 
section immediately follows the generation 
number and has the format Vnn, where V 
identifies the field as the version of 
generation number and nn (in decimal) 
identifies the version of generation of the 
file. 



Note : IBH DOS/VS System compares the entire field 
against the filename given in the DLBL card. The 
generation and version numbers are treated 
differently by the IBM OS/VS System. 
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Fields 2 through 33 constitute the Data portion of the file label. 



Fiel d Name and Length 

2. FORMAT IDENTIFIER 

1 byte, EBCDIC numeric 

3. FILE SERIAL NOMBER 

6 bytes, alphanumeric EBCDIC 



U. YOLOME SEQOEHCE NUMBER 

2 bytes, binary 

5. CREATION DATE 

3 bytes, discontinuous binary 



Description 
1 = format 1 



Uniquely identifies a file/volume relationship. It 
is identical to the volume serial number of the 
first or only volume of a multivolume file. 

Indicates the order of a volume relative to the 
first volume on which the data file resides. 

Indicates the year and the day of the year the file 
was created. It is of the form YDD, where Y 
signifies the year (0-99) and DD the day of the 
year (1-366) . 



EXPIRATION DATE Indicates the year and the day of the year the file 

3 bytes, discontinuous binary may be deleted. The form of this field is 

identical to that of field 5. 



7a. EXTENT COUNT 

1 byte, binary 



Contains a count of the number of extents for this 
file on this volume. If user labels are used, 
the count includes the user label track as a 
separate extent. This field is maintained by the 
Disk Operating System. 



7b. BYTES USED IN LAST BLOCK 
OF DIRECTORY 
1 byte, binary 



Used by IBM Operating System Virtual Storage only 
for partitioned (library structure) data sets. 
Not used by the Disk Operating System Virtual 
Storage. 



7c. 



SPARE 
1 byte 



Reserved for future use. 



8. 



SYSTEM CODE 
13 bytes 



Uniquely identifies the operating system, 



RESERVED 
7 bytes 



Reserved for future use. 



10. 



FI LE TYPE 
2 bytes 



The contents of this field uniquely identify the 
type of data file. 



Hex 

Code 

4000 

2000 

8000 

0200 



Meaning 
Sequential organization 

Direct organization 

Indexed organization 

Library organization 

Organization not defined in the file 
label 
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Field Name and Length 

11. RECORD FORMAT 
1 byte 



12. OPTION CODES 
1 byte 



13. BLOCK LENGTH 

2 bytes, binary 



14. RECORD LENGTH 

2 bytes, binary 



15. KEY LENGTH 

1 byte, binary 

16. KEY LOCATION 

2 bytes, binary 



Description 

The contents of this field indicate the type of 
records contained in the file. 



Meaning 
Variable-length records 

Fixed-length records 

Undefined format 

No track overflow 

File is organized using track 
overflow (IBH OS/VS only) 

Unblocked records 

Blocked records 

No truncated records 

Truncated records in file 

Control character ASA code 

Control character machine code 

Control character not stated 

Records are written without 
keys 

Records are written with keys 



Bits within this field are used to indicate various 
options used in building the file. 

Bit 
Position Weaning 

If on, indicates data file was created 
using write validity check. 



Bit 




Position 


Content 


and 1 


01 




10 




11 


2 







1 


3 







1 


a 







1 


5 and 6 


01 




10 




00 


7 






1-7 



Unused. 



Indicates the block length for fixed-length 
records, or maximum block size for variable- 
length blocks. 

Indicates the record length for fixed-length 
records, or the maximum record length for 
variable-length records. 

Indicates the length of the key portion of the data 
records in the file. 

Indicates the high-order position of the data 
record. 
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Field Same an 



u ^^ilH *-ll 



DescrxpLxon 



17. DATA SET INDICATORS 
1 byte 



Bits within this field are used to indicate the 
followina: 



Bit 
Position 




Meaning 
If on, indicates that this is the last 
volume on which this file normally 
resides. This bit is used by the 
DOS/VS DTFSR routine only. None of 
the other bits in this byte are used 
by the DOS/VS. 

If on, indicates that the data set 
described by this file must remain 
in the same absolute location on the 
direct-access device. 

If on, indicates that block length 
must always be a multiple of eight 
bytes. 

If on, indicates that this data file 
is security protected; a password 
must be provided in order to access 
it. 



18. SECONDARY ALLOCATION 
4 bytes, binary 



4-7 



Space. Reserved for future use. 



Indicates the amount of storage to be requested for 
this data file at end-of -extent. This field is 
used by IBH OS/VS only. It is not used by DOS/VS 
routines. 



19. LAST DSED TRACK AND 
RECORD ON THAT TRACK 
5 bytes, discontinuous binary 



20 . AHODNT OF SPACE REMAINING ON 
LAST TRACK USED 
2 bytes, binary 



Indicates the last occupied track in a consecutive 
file organization data file. This field has the 
format CCHHR. It is all binary zeros if the last 
track in a consecutive data file is not on this 
volume, or if it is not consecutive organization. 

A count of the number of bytes of available space 
remaining on the last track used by this data 
file on this volume. 



2 1 . EXTENT TYPE INDICATOR 
1 byte 



Indicates the type of extent with which the 
following fields are associated: 



Hex 

Code 

00 



Meaning 

Next three fields do not indicate any 
extent. 



01 

02 
04 



Prime area (indexed) or consecutive 
area, etc., (i.e., the extent 
containing the user's data records) . 

Overflow area of an indexed file. 

Cylinder index or master index area of 
an indexed file. 



40 
80 



User label track area. 
Shared cylinder indicator. 
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Field Name and Length 



Description 



22. EXTENT SEQOENCE NUMBER 
1 byte, binary 



Indicates the extent sequence in a multi-extent 
file. 



23. LOWER LIBIT 

4 bytes, discontinuous binary 



The cylinder and the track address specifying the 
starting point (lower limit) of this extent 
component. This field has the format CCHH. 



24. UPPER LIMIT 
4 bytes 



The cylinder and the track address specifying the 
end point (upper limit) of this extent component, 
This field has the format CCHH. 



25-28. ADDITIONAL EXTENT 
10 bytes 



These fields have the same format as the fields 
21 through 24, above. 



29-32. ADDITIONAL EXTENT 
10 bytes 



These fields have the same format as fields 21 
through 24, above. 



33. POINTER TO NEXT FILE LABEL 
WITHIN THIS LABEL SET 
5 bytes, discontinuous binary 



The disk address (format CCHHE) of a continuation 
label is needed to further describe the file. If 
field 9 indicates indexed organization, this 
field will point to a Format 2 file label within 
this label set. Otherwise, it points to a Format 
3 file label, and then only if the file contains 
more than three extent segments. If no 
additional file label is pointed to, this field 
contains all binary zeros. 
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APPENDIX D; 



TRACK FOBHATS FOR DIRECT-ACCESS STORAGE DEVICES 



The track format for the 2311, 2314, 
2319, 2321, 3330, 3340, and 3350 direct- 
access storage devices is illustrated in 
Figure 67. The names of the fields are 
given in the following discussion. 



Index Marker : All tracks start with an 
index marker. It is a signal to the 
hardware that indicates beginning of the 
track. 



Home Address : The home address, preceded 
by a gap, follows the index marker. The 
home address uniguely identifies each track 
by specifying the cylinder and head number. 



Track Descriptor Record (Record 0) : Record 
consists of two parts: a count portion 
and a data portion. The count portion is 
the same as it is for any other record {see 
the following description of count for 
record 1. The 8-byte data portion is used 
to record information used by LIOCS . The 
information in the data portion depends on 
the data organization (direct or indexed) 
that is being used. 



For direct organization, this portion in 
the form of CCEHR contains the address of 
the last record on the track and the number 
of bytes remaining on the track. This 
information is used to determine whether 
there is space for another record on the 
track. For indexed organization, the data 
portion contains the address of the last 
record in the cylinder overflow area and 
the number of tracks remaining in the 
cylinder overflow area. Record is then 
used as the cylinder overflow control 
record. 



portion for direct and indexed 
organizations . 



Count Portion. The count portion 
contains the identification of each 
record, the key length, and the data 
length. 



Identification . Each record is 
identified with its cylinder 
number, head number, or record 
number. The cylinder and head 
numbers will be the same as those 
of the home address. The record 
number will indicate a particular 
record on the track. That is, the 
first record after record will 
be record 1, followed by record 2, 
etc. This 5-byte binary field in 
the form of CCHHR is often 
referred to as the record ID. 



Key Length. The key length is 
specified in an 8-bit byte; its 
length can range from to 255. 
This field will contain a zero if 
there is no key. 



c. Data Length. The data length is 
specified in the 16 bits of the 
next two bytes. 



Note : It is the count portion 
that identifies the presence or 
absence of a key, in addition to 
indicating the data length. In 
this way, each record is unique 
and self formatting. 



Address Marker : All records after record 
will be preceded by a 2-byte address 
marker. The address marker is a signal to 
the hardware that a record is starting. 



Data Records : Data records can consist of 
a count and data portion for sequential 
organization, or a count, key, and data 



Key Portion . The key portion of the 
record is normally used to store the 
control field of the data record such 
as a man number. Direct and indexed 
files must have a key portion. 



3. Data Portion. The data portion of the 
record contains the data record. 
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Note that all records, including the 
data record, terminate with a 2-byte cyclic 
check. The hardware uses this cyclic check 
to ensure that is correctly reread what it 
had written. The cyclic check is 
cumulative and is appended to each record 
when it is written. Upon reading the 
record, the cyclic check is again 
accumulated and then compared with the 
appended cyclic check. If they do not 
agree, a data check is initiated. 

The first byte of the count portion of 
each record and the home address is 
reserved for a flag byte. If a track 



becomes defective, a utility program may be 
used to transfer the data to an alternate 
track. (Cylinders 200 through 202 are 
reserved for alternate tracks on the 2321. 
Strips 6 through 9 of subcell 19 of each 
cell are reserved for alternate tracks on 
the 2321.) In this case, a flag bit within 
the byte is set on to indicate that this is 
a defective track and the address of an 
alternate track will be placed in the 
record ID of record 0. Subsequent 
references to this defective track will 
result in the Supervisor accessing record 
for the address of the alternate track. 
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Figure 67. Track Format 
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APPENDIX E: COBOL LIBRARY SUBROUTINES 



The IBM DOS/VS COBOL Object-Time 
Subroutine Library, Program Nuiriber 
57U6-LM4, is packaged with the DOS/VS COBOL 
Compiler and also available as a separate 
product. It provides subroutines to be 
link edited with object modules produced by 
DOS/VS COBOL Compiler. It also provides 
subroutines that can be dynamically fetched 
during problem program execution. 



Printer Spacing 



The ILBDSPAO subroutine is used to 
control printer spacing when the WRITE 
statement with the BEFORE/AFTER ADVANCING 
or POSITIONING option is specified in the 
source program. 



There are several major categories of 
COBOL library subroutines: 



Input/output verb routines 

ASCII support routines 

Conversion routines 

Arithmetic verb routines 

Sort/Merge Feature interface routines 

Checkpoint (RERUN) routines 

Segmentation Feature routines 

Other verb routines 

Object-time debugging routines 

Object-time execution statistics 
routines 

Optimizer routines 

Transient routines 



The following sections describe some of 
the more commonly used subroutines. 



Tape and Sequential Disk Labels 



The ILBDUSLO and ILBDNSLO subroutines 
are used when user or nonstandard labels, 
respectively, are to be processed (LABEL 
RECORDS ARE data-name) . 



CLOSE WITH LOCK Subroutine 



The ILBDCLKO subroutine is given control 
on an OPEN if the file is ever closed with 
lock in the program. It checks whether the 
OPEN statement is used to open a file 
previously closed with lock. If the file 
was previously closed with lock, it issues 
an object-time message and terminates the 
current job. 



WRITE Statement Subroutines 



The ILBDVBLO subroutine is used to write 
variable-length blocked records. 

The ILBDDIOO subroutine is used for 
writing files with direct organization 
(DTFDA) . 

The ILBDISMO subroutine is used for 
writing files with indexed organization. 



INPUT/OUTPUT SUBROUTINES 



The input/output subroutines are used 
for the COBOL verbs DISPLAY (TRACE and 
EXHIBIT), ACCEPT, STOP (literal), READ, 
WRITE, REWRITE, OPEN, CLOSE, DELETE, and 
START printer spacing, printer overflow, 
input/output errors, disk formatting and 
extent handling, and tape and sequential 
disk labels. 



READ Statement Subroutines 



The ILBDDSRO subroutine is used to read 
sequentially the records of a directly 
organized file. 

The ILBDDIOO subroutine is used to read 
randomly the records of a directly 
organized file. 
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The ILBDISMO subroutine is used to read 
an indexed file. 



Input/Output Error Subroutines 



REWRITE Statement Subroutines 



The ILBDDIOO subroutine is used to 
update records on a directly organized 
file. 

The ILBDISMO subroutine is used to 
update an indexed file. 



DISPLAY (EXHIBIT and TRACE) Subroutines 



The ILBDDSPO subroutine formats one or 
more operands into printed lines, 
performing conversions as needed. 

The ILBDOSYO and ILBDASYO subroutines 
open SYSLST and/or SYSPCH and/or SYSIPT if 
there are DISPLAY or ACCEPT statements in a 
label declarative. 



ACCEPT and STOP (literal) Statement 
Subroutines 



The ILBDACPO subroutine is used to 
handle ACCEPT statements for both SYSIPT 
and the console, as well as the STOP 
(literal) statement. The ILBDACPO 
subroutine does not format or convert 
operands. For operands greater than 80 
characters in length, any remainder in 
excess of the nearest multiple of 80 is 
ignored when accepting data from SYSIPT. 



The ILBDSAEO subroutine is used for 
processing input/output errors that occur 
on tape and sequential disk. 

The ILBDDAEO subroutine is used for 
processing input/output errors that occur 
on directly organized files - 

The ILBDISEO subroutine is called 
whenever an input/output error occurs 
during the processing an indexed file. 

The ILBDABXO subroutine is used to issue 
a STXIT macro instruction causing control 
to be passed to it if there is an error on 
a unit-record device. 



Disk Extent Subroutines 



The ILBDFMTO subroutine writes record 
(RO) on each track of each extent of a 
directly organized file opened as output, 
and writes an end-of-file (EOF) record as 
the last record in the file. This 
subroutine is called after the file has 
been opened. 

The ILBDXTNO subroutine stores for 
subsequent use the extent information for 
directly organized files. 



3886 OCR Subroutine 



CLOSE Subroutine 



The ILBDCRDO subroutine is given control 
when a CLOSE UNIT statement is issued for a 
sequential input file with direct 
organization. 



Multiple File Tape Subroutine 



The ILBDMFTO subroutine is given control 
when a reel contains more than one file and 
there are no standard labels. 



The ILBDOCRO subroutine is used to 
perform I/O operations for the 3886 Optical 
Character Reader. 



VSAM Subroutines 



The ILBDINTO subroutine does 
initialization for VSAM processing. 

The ILBDVOCO performs VSAM open and 
close functions. 



Tape Pointer Subroutine 



The ILBDIMLO subroutine locates the 
pointer to the physical tape drive 
associated with the logical unit for a 
particular tape file. 



The ILBDVIOO performs all action 
requests for VSAM files (for example, READ, 
WRITE, REWRITE, START, DELETE). 

These routines may call the Checkpoint 
subroutine and $$BC0BR1 discussed later in i 
this chapter. " 
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Auxiliary Subroutines 



Certain input/output subroutines use 
auxiliary subroutines as follows: 



Auxiliary 
Routine 

ILBDMOVO 

ILBDIDAO 
ILBDTABO 



Used By 

ILBDSPAO, ILBDNSLO, 
ILBDVBLO 

ILBDFMTO, ILBDDSRO 

ILBDDIOO, ILBDIDAO, 
ILBDCKPO 



ASCII SUPPORT SUBRODTISES 



The subroutine described below handles 
functions necessary for files written in 
ASCII. Other functions are handled by code 
generated by the compiler or by the 
subroutine ILBDSPAO. 



Separately Signed Numeric Subroutine 



The ILBDSSNO subroutine is called to 
check the validity of signs described as 
TRAILING SEPARATE CHARACTER or LEADING 
SEPARATE CHARACTER. 



CONVERSION SUBROUTINES 



Eight numeric data formats are permitted 
in COBOL: five external (for input and 



output) and three internal (for internal 
processing) , 



The five external formats are: 



• External or zoned decimal 



• External floating-point 



• Sterling display 



• Numeric edited 



• Sterling report 



The three internal formats are: 

• Internal or packed decimal 

• Binary 

• Internal floating-point 

The conversions from internal decimal to 
external decimal, from external decimal to 
internal decimal, and from internal decimal 
to numeric edited are performed in-line. 
The other conversions are performed by the 
COBOL library subroutines shown in Table 
35. 
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Table 35. Functions of COBOL Library Conversion Subroutines 



1 1 ..... ........ ... , ., , 

1 1 Conversion | 


1 [..... ...... — ^ 

1 Subroutine Name | | | 
1 and Entry Points | From I To | 


1 ILBDEFL2 | External floating-point | Internal decimal | 
1 ILBDEFL1 1 External floating-point | Binary | 
1 ILBDEFLO 1 External floating-point | Internal floating-point | 


1 ILBDBIDQi 1 Binary I Internal decimal | 
1 ILBDBID11 1 1 i 
1 ILBDBID21 1 1 1 


1 ILBDBIEOi 1 Binary I External decimal | 
1 ILBDBIE11 1 1 1 
1 ILBDBIE21 1 1 1 


1 ILBDBII02 1 Binary I Internal floating-point | 
1 ILBDBII12 1 1 1 


1 ILBDTEF02 j Binary I External floating-point j 
1 ILBDTEF12 1 1 1 
1 ILBDTEF2 | Internal decimal | External floating-point | 
1 IFBDTEF3 | Internal floating-point | External floating-point | 


1 ILBDIDBO 1 Internal decimal | Binary | 
1 ILBDIDB1 1 External decimal f Binary I 


1 ILBDDCIl 1 Internal decimal | Internal floating-point | 
1 ILBDDCIO 1 External decimal | Internal floating-point | 


1 ILBDIFDO 1 Internal floating-point | Internal decimal | 
1 ILBDIFD1 1 Internal floating-point | External decimal | 


1 ILBDIFB1 1 Internal floating-point | Binary integer and a power | 
1 1 1 of 10 exponent | 

1 ILBDIFB23 1 1 1 

1 ILBDIFB03 1 Internal floating-point | Binary | 


1 ILBDIDRO 1 Internal decimal | Sterling report | 


1 ILBDIDTO 1 Internal decimal | Sterling non-report | 


1 ILBDSTIO 1 Sterling non-report | Internal decimal | 
(.1 ■ 1 


I^The entry points used depend on whether the double-precision number is in registers | 
1 and 1, 2 and 3, or 4 and 5, respectively. 1 
1 2The entry points are for single-precision binary and double-precision binary, | 
1 respectively. 1 
1 3This entry point is used for calls from other COBOL library subroutines. I 
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ARITHMETIC VERB SUBROUTINES 



SEGMENTATION FEATURE SUBROUTINE 



Most arithmetic operations are performed 
in-line. However, involved calculations 
with very large numbers, such as decimal 
multiplication of two 30-digit numbers, are 
performed by COBOL library arithmetic 
subroutines. These subroutine names and 
their functions are shown in Table 36. 



The Segmentation Feature requires an 
object time subroutine, ILBDSEMO. The 
ILBDSEMO subroutine performs the following 
functions when segments are needed: 



Loads and initializes independent 
segments not in storage. 



SORT/MERGE FEATURE INTERFACE ROUTINE 



Loads overlayable segments not in 
storage. 



Communication between the Sort/Merge 
program and the COBOL program is maintained 
by ILBDSRTO and ILBDMRGO. 



3. Initializes independent segments if 
the segment is in storage. 

4. Branches to desired entry points. 



CHECKPOINT (RERUN) SUBROUTINE 



OTHER VERB ROUTINES 



The ILBDCKPO subroutine issues the 
checkpoint macro instruction, which will 
write checkpoint records on a programmer- 
specified tape or disk checkpoint device. 
There are two calling sequences to this 
subroutine. The first, ILBDCKPl, is 
activated during initialization when the 
addresses of all files in the program are 
entered in a table. The second, ILBDCKP2, 
is required to take checkpoints during a 
sorting operation. 

If RERUN is requested during a sorting 
operation, ILBDSRTO must gather a list of 
physical IOCS files in use by the Sort 
program every time Sort exits at Ell, E21, 
and E31. ILBDSRTO then calls the 
checkpoint subroutine which will take a 
checkpoint of all active files. 



There are also COBOL library subroutines 
for comparisons, the verbs MOVE and 
TRANSFORM, and Other features of the COBOL 
language. 



Compare Subroutines 



The ILBDVCOO subroutine compares two 
operands, one or both of which is variable 
in length- Each may exceed 256 bytes. 

The ILBDIVLO subroutine is used in 
comparisons involving the figurative 
constant ALL 'literal*, where literal is 
greater than one character. 



Table 36. Functions of COBOL Library Arithmetic Subroutines 

Function 



r T- 

I Subroutine Name] 



ILBDXMUO 



Internal decimal multiplication (30 digits * 30 digits = 60 digits) 



ILBDXDIO 



] Internal decimal division (60 digits/30 digits = 30 digits) 



-+- 



ILBDXPRO 
ILBDFPWO 



Decimal fixed-point exponentiation 



] Floating-point exponentiation 



H 



ILliDGPwO^ 



i Floating-point exponentiation ! 

X ^ 

^The ILEDGPWO entry point is used if the exponent has a PICTURE clause specifying an | 
I integer. The ILBDFPWO entry point is used in all other cases. | 

L J 
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MOVE Subroutines 



Main Program or Subproqrairi Subroutine 



The ILBDVMOO subroutine is used when one 
or both operands is variable in length and 
in-line instructions cannot be generated 
(for example, fields overlap, etc). Each 
may exceed 256 bytes. The subroutine has 
two entry points, depending on the type of 
MOVE: ILBDVMOO (left- justified) and 
ILBDVMOl (right- justified). 

The ILBDANFO subroutine is used to move 
the figurative constant ALL ' literal •, 
where literal is greater than one 
character. 

The ILBDANEO subroutine is used to 
perform a right-or left- justified 
alphanumeric edited move. 

The ILBDSMVO subroutine handles moves to 
right- justified receiving fields either 
greater than 512 bytes in length or 
variable in length. 



TRANSFORM Subroutine 



The ILBDVTRO subroutine transforms 
variable-length items using the ILBDTRNO 
transform table. 



Class Test Subroutine 



The ILBDCLSO subroutine is used to 
perform class tests for variable-length 
items and those fixed-length items longer 
than 256 bytes. 



Note : The following tables are placed in 
the library for use by the in-line coding 
generated by the compiler and the 
subroutines called for by both the class 
test and TRANSFORM: 

ILBDATBO — Alphabetic class test 
ILBDETBO — External decimal class test 
ILBDITBO — Internal decimal class test 
ILBDUTBO — Unsigned internal decimal 
ILBDWTBO — Unsigned external decimal 



SEARCH Subroutine 



The ILBDSCHO subroutine processes each 
search argument key according to type. 



The ILBDMNSO subroutine is a 1-byte 
switch tested in the code generated for 
EXIT PROGRAM, GOBACK, INITl, and INIT2. 

The ILBDSETO subroutine must be called 
by a non- American National Standard COBOL 
program prior to any call to an American 
National Standard COBOL program. When 
calling ILBDSETO, standard linkage 
conventions must be observed; there are no 
parameters to be passed. The ILBDSETO 
subroutine sets the 1-byte switch 
(ILBDMNSO) to X'FF'. This switch is tested 
in the American National Standard COBOL 
program to determine whether it is a main 
or a called program. The name of this 
subroutine can be changed to any name 
desired by the COBOL user. 



OBJECT-TIME DEBUGGING SUBROUTINES 



Three options are available for 
object- time debugging. These are the 
statement number option (STATE), the flow 
trace option (FLOW), and the symbolic debug 
option (SYMDMP). The subroutines for the 
first two options provide debugging 
information when a program terminates 
abnormally; the subroutines for the third 
option provide debugging inforiration either 
at abnormal termination or dynamically 
during execution of a program. All of the 
subroutines are under the control of and 
are serviced by the Debug Control 
Subroutine (ILBDDBGO). This section 
discusses (1) the Debug Control Subroutine, 
and (2) the subroutines that are called in 
response to each of the three debugging 
options. 



Debug Control Subroutine 



The ILBDDBGO subroutine is included in 
the load module whenever the CBL control 
card for a program contains at least one of 
the debugging options, or when the CBL 
control card for a program requests 
execution statistics. 

Statement Number Subroutine 



The ILBDSTNO subroutine provides the 
number of the statement and the number of 
the verb being executed when abnormal 
termination occurs. If abnormal 
termination occurs during execution of an 
instruction outside of the COBOL program, 
the statement number that is provided is 
that of the last COBOL instruction 
executed. 
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Flow Trace Subroutine 



Space is allocated at compile time for a 
flow trace table using the programmer- 
specified number in the FLOW option of the 
CBL card. (If FLOW=0 was specified for a 
subprogram, no space is allocated; rather 
the subprogram shares the table space 
reserved by that program preceding it in 
the calling sequence for which a FLOW 
specification was made. ) 



OBJECT-TIME EXECUTION STATISTICS 
SUBROUTINES 



The object- time execution statistics 
subroutines enable the printing of 
execution statistics when a program 
terminates normally (via STOP RUN or GOBACK 
in the main program) and when a program 
terminates abnormally. In addition, when 
COUNT is requested, the debug control 
subroutine (described above) is also 
included in the load module. 



Each time the flow trace subroutine 
ILBDFLWO receives control from the COBOL 
program, it inserts the executing program's 
identification as well as the card number 
of the current procedure into the next 
available position in the table. When the 
end of the table is reached, subsequent 
entries overlay the first set of entries. 
The procedure is repeated until the end of 
the program or until abnormal termination. 
If abnormal termination occurs, the 
subroutine produces a list of each entry of 
the table, beginning with the earliest 
entry. 



COUNT Initialization Subroutine 



The ILBDTCOO subroutine is called from 
the debug control subroutine to get space 
for an initialize the table and chains 
which service the COUNT options. 



COUNT Frequency Subroutine 



Symbolic Debug Subroutines 



The ILBDCTIO subroutine maintains the 
execution frequency statistics. 



The symbolic debug subroutines provide a 
formatted symbolic dump, either dynamically 
at execution time, or at abnormal 
termination. 



The following subroutines perform 
initialization and process debug control 
cards: 



COUNT Termination Subroutine 



The ILBDTC20 subroutine is included in 
all COBOL load modules. It determines if 
execution frequency statistics were 
requested. 



ILBDMPIC, ILBDMPll, ILBDMP12, ILBDMP13, 
ILBDMP14, and either ILBDMPOl or 
ILBDMP02. 

To provide a diimp at abnormal 
termination, the following subroutines are 
used: 



COUNT Print Subroutine 



The ILBDTC30 subroutine formats and 
prints the execution frequency statistics. 



ILBDMP20, ILBDMP21, ILBDMP22, ILBDMP23, 
ILBDMP24, ILBDMP25 and ILBDMPOl or 
ILBDMP02. These subroutines are not 
included in the load module at link edit 
time; they are loaded dynamically during 
program execution. 

The ILBDADRO subroutine tests the 
validity of an address calculated for a 
subscripted identifier or the validity of 
the starting and ending addresses of a 
variable-length identifier used as the 
receiving field in a MOVE statement. 



OPTIMIZER SUBROUTINES 



GO TO ... DEPENDING ON Subroutine 



The ILBDGDOO subroutine is called only 
when the optimization option (OPT) has been 
specified. It is used to more efficiently 
process GO TO statements with the DEPENDING 
ON option in both segmented and 
nonsegmented programs. 
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Optimizer DISPLAY Subroutine 



Error Message Subroutine 



The ILBDDSSO subroutine is used to print 
or type certain data types on SYSLST or the 
console, respectively. 



The $$BCOBER subroutine prepares 
input/output error messages. 



TRANSIENT SUBROUTINES 



Error Hessage Print Subroutine 



The IBM DOS/VS COBOL Object-Time 
Subroutine Library includes routines that 
are dynamically fetched during program 
execution. These routines are as follows; 



The $$BC0BR1 subroutine prints the error 
messages prepared by $$BCOBER and provides 
a dump if the DUMP option is in effect. 



Reposition Tape Subroutine 



Symbolic Debug Subroutines 



With the exception of ILBDDBGO, the 
symbolic debug subroutines described 
previously are transient routines. 



SYMDMP Error Message Subroutine 



The $$BCOBEM subroutine prepares SYMDMP 
error messages. 



The $$BFCMUL subroutine resets the PUB 
pointer for a particular (SYSnnn) device to 
the same as that saved earlier by the 
stubroutine ILBDIMLO. 

Note ; if dynamically fetched subroutines 
are required during problem program 
execution, the Subroutine Library must be 
installed on the object machine. If 
dynamically fetched subroutines are not 
required during problem program execution, 
the object'^time subroutines can be link 
edited on the source machine; the 
Subroutine Library must in this case be 
installed on the source machine. 
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APPENDIX F: SYSTEM AND SIZE CONSIDERATIONS 



This appendix contains information 
concerning system and size requirements for 
the DOS/VS COBOL compiler, execution time 
considerations, and the Sort/Merge Feature. 
Additional information used in estimating 
the virtual and auxiliary storage 
requirements is contained in the 
publication IBM DOS/VS COBOL Compiler and 
Library, Installation Reference Material . 



MINIMUM MACHINE REQUIREMENTS FOR THE 
COMPILER 

1. A System/370 supported by DOS/VS. 
A minimum of 6 OK bytes of virtual 
storage is required. 

2. Five work files. The system logical 
unit SYSLNK must be assigned to a 
single area (extent) on a 2314, 2319, 
3330, 3340, 3350, or fixed block mass 
storage device. Four programmer logical 
units (SYS001 through SYS004) must 
reside on 2400, 3410, 3420 tape units, 
or on 2314, 2319, 3330, 3340, 3350, or 
fixed block mass storage devices. At 
least one programmer logical unit as 
well as the operating system must 
reside on a mass storage device (that 
is, a 2311, 2314, 2319, 3330, 3340, 
3350, or fixed block mass storage 
device) . If the three remaining 
logical units reside on tape, there 
must be a separate tape unit for each 
file. If they reside on mass storage 
devices, there must be enough space 

on those devices. An additional logical 
unit, SYS005, must be assigned if the 
symbolic debug option (SYMDMP) is 
being used. Logical unit SYS006 must 
be assigned for the FIPS flagger. 

Work file assignments must be made as 
follows: 

SYSLNK - mass storage device 
SYSOOl - mass storage device 
SYS002 - mass storage device or tape 

unit 
SYS003 - mass storage device or tape 

unit 
SYS004 - mass storage device or tape 

unit 
SYS005 - mass storage device or tape 

unit 
SYS006 - mass storage device unit 

Note that SYSLNK need only be assigned 
at compile time if the CATAL or LINK 
option is in effect. 



The filenames for SYSLNK and SYSOOl 
through SYS006 on the TLBL or DLBL 
statements are IJSYSLN, IJSYSOl, 
IJSYS02, IJSYS03, IJSYS04, IJSYS05, 
and IJSYS06, respectively. If the 
"filename" parameter of the SYMDMP 
option is specified, this filename is 
used instead of IJSYS05 on DLBL 
statements . 

3. A device, such as a printer keyboard, 
for direct operator communication - 

4. A device, such as a card reader, for 
the job input stream. 

5. A device, such as a printer or tape 
unit, for system output files. 

6. The floating-point arithmetic feature, 
if floating-point literals or 
calculations are used. 



SOURCE PROGRAM SIZE CONSIDERATIONS 



Compiler Capacity 



This section contains information which 
must be considered in determining the 
limitations on the size of a COBOL source 
program in a specific virtual storage size. 
It also contains information to aid the 
programmer in determining how his source 
program affects usage of space at 
compilation time. 

The capacity of the COBOL compiler is 
limited by two general conditions: (1) the 
total table requirement may be greater than 
the space available and (2) the fact that 
an individual table (with the exception of 
the ADCON and cross-reference tables) may 
need to be longer than 32,767 bytes. If 
either of these conditions are met during 
compilation, one of the following error 
messages will be issued: 

ILAOOOII-D NO MORE TABLE SPACE 

AVAILABLE. COMPILATION 
ABANDONED. 

ILA0003I-D A TABLE HAS EXCEEDED THE 

MAXIMUM SIZE. COMPILATION 
ABANDONED. 

ILA6007I-D TABLE HAS EXCEEDED MAXIMUM 

SIZE. LISTX, OBJECT MODULE, 
AND DECK WILL BE INCOMPLETE. 
INCREASE PARTITION. 
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In each case, compilation is terminated. 
However, in the first and third cases, or 
in the case of overflow of the ADCON or 
cross-reference table, the program may be 
recompiled with a larger size parameter. 



The compiler will accept and compile a 1500 
card program in the minimum storage of 64K. 
In this configuration, the minimum size 
compiler input/output areas must be 
allocated. If both LINK and DECK are 
specified, more storage is required for 
buffer space, which reduces the space 
available to a given program. Within this 
configuration, the compiler will accept 
programs much larger than 1500 cards; the 
specific size limitation for any storage 
size depends entirely on the statement mix 
in that program, but the limiting factors 
are described in the next section. 

The overall critical limit using the 
minimum buffer specification may be 
expressed as follows: 

2 (number of pn's + gn's + literals + 
virtuals) + 8A + S (L + 5D + 8V + 3P) < 
14336 + C 

where the number of virtuals is the number 
of calls to COBOL object-time subroutine 
entry points and subprograms specified in a 
CALL statement, and V is the number of 
unique such names; also 

A = number of entries in the ADCON table 
as defined below 

S = 1 if the Segmentation Feature is 
required and NOOPT is in effect; 
otherwise 

L = length of optimized literals 

D = number of segment discontiguities in 
the Procedure Division 

P = number of PERFORM exits and altered 
GO TO statements 

C = any storage over 64K assigned to the 
program 

It should be noted that the number of gn's 
is reduced when using OPT. 

Within this configuration, assuming no 
Report Section, the compiler will accept 
for example: 

300 procedure references assuming an 
average procedure-name length of 12 
characters 

25 OCCURS clauses with the DEPENDING ON 
option 



10 files, assuming an average of 3 
subordinate record entries 



Effective Storage Considerations 



The performance of the compiler is 
affected by the amount of storage it is 
allocated. The compiler will take 
advantage of any extra storage it is 
assigned. Furthermore, the use of a BUF 
parameter tailored to the work file device 
type in use is recommended. The following 
CBL parameters positively affect 
compile- time performance: 

OPT 

SYNTAX (CSYNTAX) 

NOLIB 

BUF 

The amount of virtual storage within the 
compiler's partition and the limitation on 
the size of an individual internal table 
are two factors that limit the capacity of 
the compiler. The limitation on the size 
of internal tables can, in some instances, 
be overcome by the spilling over of some 
tables onto external devices. However, 
spilling over may cause a severe 
degradation of performance. The storage 
limitation should not be reached by any 
reasonable use of the language. However, 
within a limited storage capacity, excessive 
use of certain features and combination of 
features in the language could make 
compilation impossible. Some of the 
features that significantly affect storage 
usage are: 

1. ADCON Table 

Each entry occupies 8 bytes. This 
table is not limited to the maximum 
size of 32,767 bytes. Entries are 
based on: 

• Number of 4096-byte segments in the 
Working- Storage Section 

• Nximber of 4096-byte segments in a 
file buffer area 

• Number of referenced procedure-names 

• Number of implicit procedure-name 
references such as those generated 
by IF, SEARCH, and GENERATE 
statements, ON SIZE ERROR, INVALID 
KEY, and AT END options, the OCCURS 
clause with the DEPENDING ON option, 
USE sentences, and the Segmentation 
Feature 

• Number of files 
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The size of this table is 
significantly reduced when using OPT. 



2. Procedure-Name Table 

This table contains the number of 
definitions written in a section and 
unresolved procedure references. 
Procedure references are resolved at 
the end of a section if the definition 
of the procedure-name is in that 
section or a preceding section. 
Therefore, forward references beyond a 
section impact space. 

3. OCCURS DEPENDING ON Table 

This table contains an entry for each 
unique object of an OCCURS clause with 
the DEPENDING ON option. The size of 
an entry is (2 + length of name + 
length of each qualifier) bytes. 

4. Index Table 

An entry is made for each INDEXED BY 
clause consisting of 11 bytes for each 
index. 

5. File Table 

An entry is made for each file 
specified in the program. Each entry 
occupies 60 bytes of storage. 

6. Report Writer Tables 

A considerable amount of information 
is maintained concerning each RD such 
as controls, sums, headings, footings, 
routines to be generated, etc. The 
contents of the table is increased by 
the existence of qualification and 
subscripting in the Report Section. 
Approximately 30 reports can be 
processed, without exceeding the limit 
of a table. 

7. Operand Table 

Entries are made depending on the 
number of operands in a statement. 
This table could reach its limits by 
the use of compound nested IF 
statements or GO TO DEPENDING ON 
statements with an excessive niomber of 
branch points. 

8. Dictionary Table 

An entry is made for each 
procedure-name and each data-name in 
the program. A procedure entry 
consists of (7 or 9 + length of name) 
bytes. A data entry consists of 
(length of name + n) bytes, where n is 
determined by the attributes of the 



data item. Some of the features that 
contribute to the value n are: 

• One byte for each character in a 
numeric edited or alphanumeric 
edited item PICTURE clause. 

• Five bytes for an elementary item, 
with a sterling report PICTURE 
clause. 

• Three bytes for an item 
subordinate to an OCCURS clause. 

In the statistics output, an 
indication is given if spill of 
this table occurred. If spill 
occurred, increasing the partition 
size assigned to the compiler 
should increase performance. 

9. Literal Tables 

The total length of all literals 
(after optimization) may not exceed 
32511 bytes. No more than 16255 
literals may be specified. 

If the segmentation feature is used, 
an area corresponding to the total 
length of all optimized literals must 
be kept free during the time the ADCON 
table is being built. Therefore, a 
segmented program with literals may 
need more storage. 

10. Miscellaneous Tables 

The existence of the following items 
causes entries to be made into tables 
and impacts the total space required 
for compilation. 



SAME (RECORD) AREA clause 

Subscripting 

Intermediate Arithmetic Results 

Complex Arithmetic Expressions 

Complex Logical Expressions 

APPLY clauses 

Special-Names 

RERUN clauses 

Error messages 

XREF 

Segmentation feature 

VERBSUM/VERBREF 



EXECUTION TIME CONSIDERATIONS 



The amount of virtual storage must be 

sufficient to accomodate at least: 

• The selected control program 

• Support for the file processing 
techniques used 
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• Load module to be executed 



• Dynamic storage for VSAM, 3886 
processing, and COUNT. 



When the OPTIMIZE option is specified, 
the number of procedure blocks in the 
program cannot exceed 255. A procedure 
block is approximately 4096 bytes of 
Procedure Division code. 

COBOL programs compiled with any of the 
symbolic debugging options (STATE, FLOW, 
SYMDMP) have different requirements at 
execution time than similar programs 
compiled without these options. The 
following differences should be noted: 

• If the SYMDMP option is in effect, the 
work file required at compile time 
(SYS005) must be present at execution 
time. 

• The size of the load module will 
increase by about 3200 bytes if the 
SYMDMP option is in effect. In 
addition, since the object-time 
subroutine that provides SYMDMP output 
is invoked dynamically, the programmer 
must provide space in the partition 
amounting to S + V. When only an 
abnormal termination dump is required, 

S = 4000 and V = 0; that is, 4000 extra 
bytes must be available. When dynamic 
diomps are required, S = 11,000 and V is 
approximately 25 * number of line- 
control cards + 10 * the number of 
identifiers specified on these line- 
control cards. 

• The size of the load module will 
increase by 4500 + V bytes if the FLOW 
option is in effect. V is a variable 
factor that depends upon the number 
specified by the programmer on the CBL 
card. V is calculated using the 
formula : 



• A SIZE parameter must be specified on 
the EXEC card for VSAM and 3886 
processing and if COUNT is requested on 
the CBL card. 

COBOL programs with the execution 
frequency option COUNT have the following 
additional requirements: 

• The size of the load module will 
increase by about 6000+V bytes (if any 
of the symbolic debugging options are 
in effect) to 8900+V bytes (if the 
symbolic debugging options are not in 
effect) . Vis calculated using the 
formula: 

V=(54 * pgm)+(8*nvb)+(7*npr)+((4+sym) * 
vbl)+pnl 

where 

pgm is the number of COBOL program 
units being monitored by COUNT 

nvb is the number of verbs in the 
program units 

npr is the number of procedure-names 
plus inserted procedure-names in the 
program 

sym is zero xanless SYMDMP is in 
effect, then it becomes two 

vbl is the number of verb blocks in 
the program (which can be estimated 
as 1/3 the number of verbs in the 
program) 

pnl is the sum of the lengths of the 
procedure- names . 

• The increase in dynamic storage in 
estimated using the formula 

D = 512+(72*pgm)+(4 * vbl) 

where 



V=92+4*nn+8*p 

where "nn" is any number from through 
99, and "p" is the number of 
procedure-names in the program. 

The size of the load module will 
increase by 4600 + V bytes when the 
STATE option is in effect. V is 
approximately 5 ♦ the number of COBOL 
statements in the program. 

When both SYMDMP and FLOW are in 
effect, the size of the load module 
will increase by the amount it would 
for FLOW alone, and the size of the 
partition increases by the amount it 
would for SYMDMP alone. 



pgm is the number of COBOL programs 
being monitored by COUNT 

vbl is the number of verb blocks in 
the program (which can be estimated 
as 1/3 the number of verbs in the 
program) - 



MULTIPROGRAMMING CONSIDERATIONS 



In a system which supports the batch- job 
foreground (NPARTS = 2 or more) and private 
core-image library options, the Linkage 
Editor can execute in any foreground 
partition (as well as the background 
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partition) provided a miniiruin of lUK or 64K 
of storage is assigned to the partition. 
When executing in a foreground partition, a 
private core image library must be 
assigned. 

In the multiprogramming environment 
described above, the COBOL compiler can be 
executed in any partition having a minimum 
of 64 bytes in the following manner: 

At system generation time, link edit 
the compiler in the background 
partition and place it in the system 
core image library. 



2. Standard instruction set. 

3. At least one 2314, 2319, 3330, 3333, 
3340, or 3350 work file. (System 
residence requirements may necessitate 
having an additional disk storage unit 
for sorting.) 

4. One IBM 1403, 1443, or 3211 Printer, 
or one IBM operator communication 
device (for example, 3215) . 

5. One IBM 1442, 2501, 2520, 2540, 3505, 
3525, or 2560 Card Reader, or one IBM 
2400 or 3400 Series Magnetic Tape Unit 
(7- or 9-track) assigned to SYSIPT and 
SYSRDR. 



SORT FEATURE CONSIDERATIONS 



The DOS/VS SORT/MERGE Program Product, 
Program Number 57 4 6- SMI, must be executed 
under control of DOS/VS. It requires the 
following minimum machine configuration: 

1. The DOS/VS SORT/MERGE Program Product 
uses 16K bytes; additional storage is 
needed for DOS/VS and for user-written 
routines (that is, the COBOL program, 
etc. ) . 

Note ; Performance often increases 
significantly if 50K is available for 
operation of the Sort/Merge program. 
At the lOOK level, the performance 
could be even higher. 



6. Three IBM 2400 or 3400 Series Magnetic 
Tape Units for work files when tape 
units are to be used for intermediate 
storage. 

For specific size, device, and work file 
requirements of the other Sort/Merge 
products, see the respective Programmer's 
Guides as noted in the preface. 

Note ; If a size parameter is used in the 
//EXEC statement, it should be used as 
follows: 



//EXEC , S I ZE= (AUTO , nK ) 

where NK has to meet specific Sort 
storage requirements. 
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APPENDIX G: COMMDNICATION REGION 



PROGRAM COMMUNICATION 



For each partition, the supervisor contains 
a storage area called the communication region. 
The supervisor uses the communication region, 
and your program also can use it. Your 
program can check the communication region of 
the partition in which your program runs; your 
program can also modify the user area of this 
communication region. 

Figure 68 shows the portion of the communication 
region containing information of interest. This 
information is also described below. 



Byte ( s ) Information 

0-7 Calendar date. Supplied from system 
date whenever the JOB statement is 
encountered. The field can be two 
forms : mm/dd/yy or dd/mm/yy where 
mm is month, dd is day, yy is year. 
It can be temporarily overridden by 
a DATE statement. 

8,9 Address of the problem program area. 

10,11 Address of the beginning of the 
problem program area. 

12-22 User area for communication within 
a job step or between job steps. 
All 1 1 bytes are set to zero when 
the '//JOB' JOB control 'statement 
is encountered. 

Note : The COBOL compiler uses bytes 
12 and 13. 



Byte(s) Information 

23 UPSI (user program switch 

indicators) . Set to binary zero 
when the JOB statement for the 
job is encountered. Initialized 
by UPSI job control statement. 

The condition-name associated 
with the status of the UPSI 
switches can be specified in the 
COBOL program via the 
Special-Names paragraph of the 
Environment Division. The 
condition-name associated with 
each may be tested in the 
Procedure Division of the COBOL 
program. 

24-31 Job name as found in the JOB 
statement for the job. 

32-35 Address of the uppermost byte 
of the program area. If the 
program was initiated with the 
SIZE parameter in the EXEC job 
control statement, this address 
gives the highest duty of the 
area determined by the SIZE 
parameter. 

If the SIZE parameter was not 
specified, the address is the 
highest address in the partition 
(either real or virtual) . 

36-39 Address of the uppermost byte 
of the current phase placed in 
the program area by the last 
FETCH or LOAD macro in the job. 
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Figure 68. Communication Region in the Supervisor 
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Bytefs) Information 

40-43 Highest ending virtual storage 
address of the phase among all 
the phases having the same first 
four characters as the operand 
on the EXEC statement. For the 
background partition only, job 
control builds a phase directory 
of these phases. The address 
may be incorrect if the program 
loads any of these phases above 
its link-edited origin address 
and the relocating loader is not 
used. If the EXEC statement has 
no operand, job control places 
in this location the ending 
address of the phase just 
link-edited. 

44,45 Length of program label area. 

The COM-REG special register may be used 
to access bytes 12-22 of the communication 
region. 
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APPENDIX H: SAMPLE JOE DECKS 



This appendix illustrates the necessary 
job control statements and their sequence 
for five typical programs: 



1„ Creating a Direct File 

2. Retrieving and Updating a Direct File 

3. Creating an Indexed File 



Retrieving and Updating an Indexed 
File 

Sorting an Unlabeled Tape File 



In all five programs the programmer has 
requested the following compiler options 
through the OPTION control statement: 

NODECK — No punched card output for the 
object program is needed. 

LINK — The object module is to be 
linkage edited. 

LIST — The COBOL source statements 
are to be printed on SYSLST. 

LISTX — A Procedure Division map with 
global tables, literal pool, 
and register assignments is to 
be printed on SYSLST. 



SYM 



ERRS 



A Data Division map is to be 
printed on SYSLST. 

The diagnostic messages of the 
COBOL compiler are to be 
printed on SYSLST. 



The EXEC FCOBOL statement calls for 
execution of the FCOBOL compiler. 

By using the CBL card, the programmer 
indicates that in this source program the 
quotation mark (") is used for nonnumeric 
literals. 

The ASSIGN clause in the COBOL source 
program specifies a system-name with the 
following fields: 

(Non-VSAM) 

SYSnnn-class-device-organization(-name] 

(VSAM) 

SYSnnn [-class] [-device] [-organization] 
[-name] 

The ASSGN control statement for a file 
must specify the same logical unit as the 
SYSnnn field of system-name. The ASSGN 
statement assigns the logical unit to a 
specific hexadecimal address. The address 



specified must be associated with the 
device whose number is given in the device 
field of system-name. 

The DLBL control statemerot for a labeled 
file on a mass storage device must contain 
the same name as system-name. This is the 
name by which the file is known to the 
control program. (The name field of 
system-name is optional- If name is 
omitted, the DLBL statement must specify 
the logical unit (SYSnnn) as the 
file-name.) The code field of the DLBL 
statement must correspond to the class and 
organization fields of system-name as 
follows: 



DLBL 
'code' 

SD 



ASSIGN 1 ASSIGN 
"class" j "organization" 



DA 

ISC 

ISE 



DA or UT 1 

r 



DA 
DA 
DA 



AS (entry- 

segtienced file) 
omitted (key- 

sequefhced file) 

A or U, D or W 

I, , . 

i 



If SYSnnn is omitted from the first 
EXTENT control statement for a file on a- 
mass storage device, then the logical 
unit is determined from the SYSnnn field 
of the COBOL system-name; if SYSnnn is 
included in the first EXTENT statement 
and differs from SYSnnn of the system- 
name, the EXTENT card specification 
overrides the COBOL source specification. 
(Subsequent EXTENT statements for the 
same file, if they immediately follow 
the first, may omit this field.) The 
type of the extent must be compatible 
with the organization field of system- 
name as follows: 



EXTENT 
"type" 



(data area, no 
split cylinder) 



(overflow area for 
indexed file) 

(index area for 
indexed file) 

(data area, split 
cylinder) 



ASSIGN 
'organization" 



S, A, U, I, D, W 

AS 

I 



S, A, U, I, D, W 
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DIRECT FILES 



The following two examples illustrate 
the job control stateitients necessary for 
programs that create and update a direct 
file. 

In the COBOL source programs, the 
programmer has written: 

SELECT DA-FILE ASSIGN TO 

SyS015-DA-2311-A-MASTER. . . 

SELECT CARD-FILE ASSIGN TO 
SYS007-UR-2540R-S. . . 



(Note that in the EXTENT statement, the 
relative track number (1020) is not 
required for the input DA file of the 
updating program, since the system will use 
the file labels for this information. ) 



The EXEC statement begins execution of 
the problem program, and is followed by 
input data. 



The /♦ statements indicate end-of-data, 
the /6 statement indicates end-of-job. 



In the READFILE source program, the 
programmer has written: 

SELECT PRINT-FILE ASSIGN TO 
SYS008-UR-2403-S. . . 

(Note the relationship between the 
system-names in the source programs and the 
control statements.) 

The LBLTYP statement defines the amount 
of storage to be reserved to process labels 
for the DA file. The file has one extent. 

The EXEC LNKEDT Statement causes the 
object program to be link edited. 

An ASSGN control statement assigns 
logical unit SYS007 to the hexadecimal 
address OOC — a 25U0R Card Reader. 

In the updating program, another ASSGN 
statement assigns logical unit SYSOOS to 
the hexadecimal address ODE — a 1403 
Printer. 

The next series of statements identify 
the direct file completely. 

The ASSGN statement identifies the file 
as residing on logical unit SYS015, which 
has the hexadecimal address of 192 — a 
2311 Disk Drive. 

The DLBL statement specifies the 
filename as MASTER, with an expiration date 
of the 365th day of 1973, and that the file 
has direct organization (DA) . 

The EXTENT statement specifies that the 
file residing on logical unit SYS015 has a 
serial number 111111, that the extent is a 
data area with no split cylinder and that 
this is the first (and only) extent for the 
file (type and sequence number 1,0), that 
the file begins on relative track 1020 
(track of cylinder 102), and that the 
file occupies 100 tracks. 



Creating a Direct File 



// JOB CREATEDA 

// OPTION NODECK, LINK, LIST, LISTX,SYM, ERRS 
y/ EXEC FCOBOL 
CBL QUOTE 

{COBOL source deck} 
/♦ 

// LBLTYP NSD(Ol) 
// EXEC LNKEDT 
// ASSGN SYS007,X'00C» 
// ASSGN SYS015,X'192' 
// DLBL MASTER,, 74/365, DA 
// EXTENT SYS015, mill, 1,0, 1020, 100 
// EXEC 



/♦ 
/6 



{input data cards} 



Retrieving and Updating a Direct File 



// JOB READFILE 

// OPTION NODECK, LINK, LIST,LISTX,SYM, ERRS 
// EXEC FCOBOL 
CBL QUOTE 

{COBOL source deck} 

/* 

// LBLTYP NSDCOl) 

// EXEC LNKEDT 

// ASSGN SYS007,X'00C' 

// ASSGN SYSOOS, X'OOE* 

// ASSGN SYS015,X*192* 

// DLBL MASTER,, 7 4/3 6 5, DA 

// EXTENT SYS015, mill, 1,0,1020,100 

// EXEC 



/* 

/& 



{input data cards} 
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INDEXED FILES 



The following two examples illustrate 
the job control statements necessary for 
programs that create and update an indexed 
file. 

In the CREATEIS source program, the 
programmer has written: 

SELECT IS-FILE ASSIGN TO 

SyS015-DA-2314-I-MASTER 
ACCESS IS SEQUENTIAL 
RECORD KEY IS RtC-ID. 

In the RANDIS source program, the 
programmer has written: 

SELECT IS-FILE ASSIGN TO 

SYS015-DA-2314-I-MASTER 
ACCESS IS RANDOM 
NOMINAL KEY IS KEY- ID 
RECORD KEY IS REC-ID. 

SELECT PRINT-FILE ASSIGN TO 

SYS008-UR-1403-S 
RESERVE NO ALTERNATE AREAS. 

In both source programs, he has written: 

SELECT CARD-FILE ASSIGN TO 
SYS007-UR-2540R-S. 

I -O- CONTROL. 

APPLY MASTER-INDEX TO 2311 ON IS-FILE. 

(Note the relationship between the 
source program statements and the job 
control statements.) 

The LBLTYP statement defines the amount 
of storage reserved to process labels for 
the indexed file. The file has three 
extents: a master index extent, a cylinder 
index extent, and a data extent. 

The EXEC LNKEDT Statement causes the 
object module to be link edited. 

An ASSGN control statement assigns 
logical unit SYSOO? to the hexadecimal 
address OOC — a 2540R Card Reader. 

In the retrieval program, another ASSGN 
statement assigns logical unit SYS008 to 
the hexadecimal address OOE — a 1403 
Printer. 

The next ASSGN statement assigns logical 
unit SYS 015 to the hexadecimal address 193 
— a 2314 Disk Drive. 

The DLBL statement names the file as 
MASTER, and indicates the expiration date 
as the 365th day of 1974. In the file 
creation program, the file label is indexed 
sequential using Load Create (code ISC) ; in 



the retrieval program, the file label is 
indexed sequential using Load Extension, 
Add or Retrieve (code ISE) . 



The first EXTENT statement is identified 
as a master index (type and sequence 
numbers are 4, 0) , and the relative track is 
i 900 (the extent begins on cylinder 90 
track 0), and the extent is 20 tracks long. 



The second EXTENT statement is 
identified as a cylinder index (type and 
sequence number are 4,1), the relative 
track is 1820 (the extent begins on 
cylinder 91, track 0), and the extent is 20 
tracks long. 



(Note that the extents assigned to 
master and cylinder indexes must be 
contiguous, and that the master index must 
precede the cylinder index on the disk 
pack. Also note, that if a master index is 
not requested, the first extent is that for 
the cylinder index, which would be type 4, 
sequence number 1.) 



The third EXTENT statement is identified 
as a data area (type 1) and is the third 
extent named for this file- The relative 
track is 0020 (the extent begins on 
cylinder 1, track 0), and the extent is 
1760 tracks long. 



End-of-data is indicated with the /* 
statement; end-of-job is indicated with the 
/S statement. 



Creating an Indexed File 



// JOB CREATEIS 

// OPTION NODECK, LINK, LIST, LISTX,SYM, ERRS 
// EXEC FCOBOL 
CBL QUOTE 

{COBOL source deck} 
/* 

// LBLTYP NSD(03) 
// EXEC LNKEDT 
// ASSGN SYS007,X"00C'' 
// ASSGN SYS015,X'193' 
// DLBL MASTER, ,74/365, ISC 
// EXTENT SYS015, mill, 4, 0,1800, 20 
// EXTENT SYS015, mill, 4, 1,1820, 20 
// EXTENT SYS015, mm, 1,2,0020,1760 
// EXEC 



/♦ 
/& 



{input data card} 
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Retrieving and Updating an Indexed File 



// JOB RANDIS 

// OPTION NODECK,LINK, LIST, LISTX,SYM, ERRS 

// EXEC FCOBOL 

{COBOL source deck} 
// LBLTYP NSD(03) 
// EXEC LNKEDT 
// ASSGN SYS007,X'00C' 
// ASSGN SYS008,X'00E' 
// ASSGN SYS015,X'193' 
// DLBL MASTER,, 7 3/3 6 5, ISE 
// EXTENT SYS015, mill, 4,0, 1800, 20 
// EXTENT SYS015, mill, 4, 1,1820, 20 
// EXTENT SYS015,111111, 1,2, 0020, 1760 
// EXEC 



/* 
/& 



{input data cards} 



FILES USED IN A SORT OPERATION 



The following example illustrates the 
job control statements necessary for a 
program that sorts an unlabeled tape file. 

In the COBOL source program, the 
programmer has written: 

SELECT NET-FILE- IN ASSIGN TO 
SYS007-UT-2400-S. 

SELECT NET-FILE-OUT ASSIGN TO 
SYS008-UT-2400-S. 

SELECT NET-FILE ASSIGN TO 3 
SYS001-UT-2400-S. 

NET-FILE-IN is the input file; 
NET-FILE-OUT is the output file; NET-FILE 
is the sort work file, which utilizes three 
tape units. 



(Note the relationship between the 
system-names in the COBOL source program 
and the control statements.) 



The EXEC LNKEDT Statement causes the job 
to be link edited. 

The first two ASSGN control statements 
assign the logical unit SYS007 to 
hexadecimal address 181, and logical unit 
SYS008 to hexadecimal address 182. SYS007 
is the sort input file, and SYS008 is the 
sort output file. 

The last three ASSGN statements assign 
logical unit SYSOOl to hexadecimal address 
183, logical unit SYS002 to hexadecimal 
address 281, and logical unit SYS003 to 
hexadecimal address 28 2. SYSOOl, SYS002, 
and SYS003 are the logical units that must 
be used for sort work files. The sort work 
files must be assigned to 9-track tape 
units. At this installation, 9-track tape 
drives are associated with hexadecimal 
addresses 183, 281, and 282. 



Sorting an Unlabeled Tape File 



// JOB SORTCOB 

// OPTION NODECK, LINK, LIST, LISTX,SYM, ERRS 
// EXEC FCOBOL 
CBL QUOTE 

{COBOL source deck} 
// EXEC LNKEDT 
// ASSGN SYS007,X'181'' 
// ASSGN SYS008,X"182" 
// ASSGN SYSOOl, X" 183* 
// ASSGN SYS002,X"281" 
// ASSGN SYS003,X*282' 
// EXEC 
/S 
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APPENDIX I: DTJGNOSTIC MESSAGES 



This appendix contains information on how to generate a listing of 
compile-time diagnostic messages. 



COMPILE-TIME MESSAGES 

The user can request a complete listing of the diagnostics generated 
by this compiler simply by compiling a program with a PROGRAM-ID of 
ERRMSG. For a description of the formats of compiler diagnostics and 
information about generating this listing, see the chapter entitled 
"Output" in this publication. 



OPERATOR MESSAGES 

This section lists the messages issued to SYSLOG by the IBM DOS/VS 
COBOL Compiler and Library. All of the messages listed are also issued 
on SYSLST. 

The following messages are issued during compilation on SYSLOG. They 
are also printed on SYSLST with the prefix ILA. 

C100I PARTITION IS LESS THAN 64K 

Explanation : At least 64 K is required to compile using D0S/7S 
COBOL. Probable user error. 

System Action : The compilation is terminated. 

Programmer Response : Not applicable. 

Operator Response : Use the ALLOC command to allocate at least 
64K to the partition (refer to BUF option) . If the problem 
recurs, do the following to complete your problem determination 
action before calling IBM for programming support. 

1. Execute the HAP command and save the output. 

2. Have the source deck, control cards, output listing, and 
console sheet available. 

C101I DEVICE NOT ASSIGNED - SYSnnn . 

Explanation : (nnn is either 001, 002, 003, or OOU.) The 
specified logical unit is unassigned and must be assigned. 
Probable user error. 

System Action : The compilation is terminated. 

Programmer Respons e: Not applicable. 



Operator Response : Use the ASSGN command to assign a physical 
unit (magnetic tape or disk) to the file indicated. If the 
problem recurs, do the following to complete your problem 
determination action before calling IBM for programming 
support: 
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1. Execute the LISTIO command and save the output. 

2. Have the source deck, control cards, output listing, and 
console sheet available. 

C102I UNSaPPOBTED DEVICE TYPE - SYSnnn. 

Explanati on: (nnn is either 001, 002, 003, or OOU.) The 
specified file must be a tape or disk file for SYS002 through 
SYS004. SYS001 should be assigned to disk; however, in small, 
simple programs that do not require dictionary spill, it is 
sometimes possible to compile with the spill file (SYS001) 
assigned to tape. If any spill does occur, an input/output 
error may occur. Compile-time statistics will say "DICTIONARY 
SPILL HAS OCCURRED". No mention is made of dictionary spill in 
the compile-time statistics if spill does not occur. Probable 
user error. 

System Action : The compilation is terminated. 

Programmer Response : Not applicable. 

Operator Response : Use the ASSGN command to assign the 
appropriate physical unit to the file indicated — SYS001 
should be assigned to a magnetic tape or disk unit. If the 
problem recurs, do the following to complete your problem 
determination action before calling IBM for programming 
support: 

1. Execute the LISTIO command and save the output. 

2. Have the source deck, control cards, output listing, and 
console sheet available. 

C103I END OF FILE ON SYSIPT. 

Explanation : End-of-file was encountered in the initialization 
phase; no source statements were found. Probable user error. 

System Action : The compilation is terminated. 

Programmer Response : Not applicable. 

Operator Response : Ensure that a /* card does not precede the 
source deck, or add the source deck to the job stream. If the 
problem recurs, do the following to complete your problem 
determination action before calling IBM for programming 
support: 

1. Execute the LISTIO command and save the output. 

2. Have the source deck, control cards, output listing, and 
console sheet available. 

ClOm SYS001 FILE NOT ASSIGNED TO DISK 

Explanation : In small, simple programs that do not require 
dictionary spill, it is sometimes possible to compile with the 
spill file (SYS001) assigned to tape. However, if any spill 
does occur, an input/output error may occur. Any compilation 
which spills the dictionary will contain a message in 
compile-time statistics. User error. 

System Actio n: The compilation continues. 

Programmer Action : Not applicable. 
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Operator Response ; Use the ASSGN coiriinand to assign SYSOOl to a 
disk unit. If the problem recurs, do the following to complete 
your problem determination action before calling IBM for 
programming support: 

1. Execute the LISTIO command and save the output. 

2. Have the source deck, control cards, output listing, and 
console sheet available. 

C105I W-CANNOT OPEN SYS0 05 — SYMDMP IGNORED- 

Explanation ; The SYMDMP option has been specified, but the 
file needed for symbolic debug cannot be opened since SYS005 is 
unassigned. Probable user error. 

System Action ; The SYMDMP option is canceled, and the 
compilation continues. 

Programmer Response ; Not applicable. 

Operator Response : Use the ASSGN command to assign SYS005 to a 
physical unit. If the problem recurs, do the following to 
complete your problem determination before calling IBM for 
programming support: 

1. Execute the LISTIO command and save the output. 

2. Have the source deck, control cards, output listing, and 
console sheet available. 

C106I SYS006 IS NOT A DISK. NOLVL ASSUMED. 

Explanation ; The specified logical unit is not assigned to a 
disk. 

System Action ; Compilation continues with NOLVL. 

Programmer Response : Not applicable. 

Operator Response ; Use the ASSGN command to assign SYS006 to a 
disk unit. 



OBJECT-TIME MESSAGES 

The following messages are normally issued on SYSLOG. 

CllOA STOP literal 

Explanation ; The programmer has issued a STOP literal 
statement in the COBOL source program. 

System Action ; Awaits operator response. 

Programmer Response ; Not applicable. 

Operator Response : Operator should respond with end-of-block, 
or with any character in order to proceed with the program. 

ClllA AWAITING REPLY 

Explanation : This message is issued in connection with the 
Full American National Standard COBOL ACCEPT statement. 

System Action ; Awaits operator response. 

Programmer Response ; Provide the operator with instructions. 
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Operator Response : 
the prograinmer . 



The operator should reply as specified by 



The following messages are issued on SYSLOG and SYSLST prior to 
cancellation of the job. If the DUMP option is specified, a partial 
dump is taken from the problem program origin to the highest storage 
location of the last phase loaded. When this occurs, the eight bytes 
immediately preceding the DTF are destroyed. The messages have the 
form: 

Cmmml SYSnnn filename DTFaddress text 



where: 



nnn is equal to 001 through 255 

filename is seven or fewer characters and is generated from the 

file-name specified in the SELECT sentence. 
address is the hexadecimal address of the file's DTF table. 
mmm and text correspond as follows : 

mmm text 

112 DATA CHECK 

113 WRONG LENGTH RECORD 

114 PRIME DATA AREA FULL 

115 CYLINDER INDEX TOO SMALL 

116 MASTER INDEX TOO SMALL 

117 OVERFLOW AREA FULL 

118 DATA CHECK IN COUNT 

119 DATA CHECK IN KEY OR DATA 

120 NO ROOM FOUND 

121 DASD ERROR 

122 DASD ERROR WHILE ATTEMPTING TO WRITE 

RECORD ZERO 

123 FILE CANNOT BE OPENED AFTER CLOSE WITH LOCK 

124 CYLINDER AND MASTER INDEX TOO SMALL 

125 NO EXTENTS 

127 NO EOF RECORD WRITTEN IN PRIME 

DATA AREA 

128 UNRECOVERABLE I/O ERROR 

129 3540 EQUIPMENT CHECK 

130 INPUT/OUTPUT ERROR. FILE STATUS SET TO XX 
NEAR REL LOC. XXXXXX. 

131 USABLE TO OPEN FILE 'SYSnnn*. CANCELING. 

132 SIZE NOT SPECIFIED OR INSUFFICIENT GETVIS AREA. 
140 INVALID SEPARATE SIGN CONFIGURATION. 



C125I 



Explanation : Condition indicated occurred on SYSnnn. 

System Action : The job is cancelled. 

Programmer Response ; Rerun the job or add a user Declaractive 
Section to the Procedure Division of the source program to 
handle errors within the program. 

If the problem recurs, do the following before calling IBM 
for programming support: have source deck, control cards, 
compiler output, and console sheet available. 

Operator Response : Not applicable. 

NO EXTENTS 

Explanation ; During CLOSE UNIT processing, no extent is found 
for the next volume. 

System Response : The job is cancelled. 

Programmer Response ; Rerun job with proper EXTENT (XTENT) 
statements. 
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Operator Response : Not applicable. 

If the problem recurs, do the following before calling IBS 
for programming support: have source deck, control cards, 
compiler output, and console sheet available. 

The following message is issued on SYSLOG: 

C126D SYSnnn IS IT EOF? 

Where nnn is equal to 001 through 255 

Explanation : A tapemark was just read on an unlabeled tape 
file described at compilation time as having more than one 
reel. 

System Action : Awaits response from operator. 

Programmer Response : Not applicable. 

Operator Response : The operator must respond either with N if 
is end of volume, or with Y if it is end of file. 

The following messages are issued on SYSLOG and SYSLST: 

C127D NO EOF RECORD WRITTEN IN PRIHE DATA AREA 

Explanation : During CLOSE processing of an ISAH file opened 
OUTPUT, no room was found to write EOF record. 

Programmer Response : Rerun the job with the proper EXTENT. 

If the problem recurs, do the following to complete your 
problem determination action before calling IBH for programming 
support. Have source deck, control cards, compiler output, and 
console sheet available. 

Operator Response ; Not applicable. 

C128D UNRECOVERABLE I/O ERROR 

Explanation : This is probably a hardware error on tape. 

Programmer Response : Not applicable. 

Operator Response ; Rerun the job. 

If the problem recurs, do the following to complete your 
problem determination action before calling IBM for programming 
support. Have source deck, control cards, compiler output, and 
console sheet available. 

C129I VSAH SUBROUTINE ERROR. CANCELING JOB. 

Explanation : The subroutine has encountered an unrecoverable 

error. This can occur when a VSAM OPEN, CLOSE, or ACTION request 
(GET, PUT, etc.) returns an error code from which the subroutine 
has no means of recovering, or when one of the VSAM macros (SHOWCB, 
GENCB, etc.) returns a non-zero return code. All such conditions 
indicate an error found in the subroutines and/or in VSAM. 

Action : The program is canceled with a dump. 

Programmer Response : Submit an APAR with the dump. 

If the problem recurs, do the following before calling IBH 
for programming support: have source deck, control cards, and 
compiler output available. 
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C130I INPUT/OUTPOT ERROR. FILE STATOS SET TO XX NEAR REL LOC. 
xxxxxx. 

Explanation : An I/O error has occurred on the file being 
accessed by the COBOL statement at or near the relative 
location given in the message, and the user has no USE 
declarative for that file. 

Action: Control returns to COBOL at the statement following 
the COBOL request that caused the error. 

Programmer Response : If the error occurred on a READ 
operation, processing can continue. If the error occurred on a 
WRITE operation, there may be a loss of data. 

If the problem recurs, do the following before calling IBM 
for programming support: have source deck, control cards, and 
compiler output available. 

C131I ONABLE TO OPEN FILE »SYSnnn». CANCELING. 

Explanation ; The VSAM OPEN or CLOSE request gave a return code 
of X»68* or X»6C» because of invalid time stamps in the VSAH 
catalog or VSAH file. The VSAM catalog or file should be 
recreated. See DOS/YS Supervisor and I/O Macros for more 
detail on the OPEN/CLOSE return codes. 

Action: The job is canceled. 

Programmer Response : Recreate the VSAM catalog and/or file. 

If the problem recurs, do the following before calling IBM 
for programming support: have source deck, control cards, and 
compiler output available. 

C132I SIZE NOT SPECIFIED OR INSUFFICIENT GETVIS AREA. 

Explanation ; A GETVIS SVC to obtain GETVIS space 
for VSAM control blocks was unsuccessful. 

Action ; The job is canceled. 

Programmer Response ; Increase the partition size 
and resubmit the job with a SIZE parameter in the 
EXEC statement. 

C140I INVALID SEPARATE SIGN CONFIGURATION 

Explanation: During execution of a COBOL program, an invalid 
sign was detected for a separately signed item. 

Action : The job is terminated. 

Program mer Response : Probable user error. Correct program's 
input data before reexecuting. 

If the problem recurs, do the following before calling IBM 
for programming support: have source deck, control cards, 
compiler output, and data available. 
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The following messages (C150I-C170I) are listed on SYSLST. The 
messages have the form: 

{program-id \ 
> text 
card/verb number) 

Messages C150I through C162I may appear interspersed among the SYHDHP 
control cards at the point at which the error is encountered. 
Program-id is provided for all messages except C150I through C152I. For 
these, the card/verb number of the corresponding line-control card is 
given instead. The program-id associated with C150I through CI 521 can 
be determined from the nearest preceding program-control card. 

Messages C153I through C155I may also appear in the midst of the dump 
output if the error condition is not recognized until dumping has 
started. 

C150I IDENTIFIER NOT FODND. 

Explanation ; An identifier specified on the line-control card 
cannot be found in the program or is invalid. Level-66 and 



Appendix I: Diagnostic Messages 312.1 



level-88 items and items defined under an RD are invalid 
requests. 

Action ; The dump request for this identifier is ignored. 

Programmer Response : Probable user error. Before reexecuting, 
ensure that no requests have been made on the line-control card 
for the dum.ping of identifiers that have not been defined or 
that are invalid. 

If the problem recurs, do the following before calling IBM 
for prograirm.ing support: have source deck, control cards, and 
compiler output available. 

C151I CARD NUMBER NOT FOUND 

Explanation ; The card number specified on the line-control 
card is not within range of the Procedure Division. 

Action: The line-control card which specifies the nonexistent 
card number is skipped. 

Programmer Response ; Probable user error. Ensure that any 
card n jmber specified on a line-control card is within range of 
niombers specified for source program before reexecuting. 

If the problem recurs. do the following before calling IBM 
for programming support: have source deck, control cards, and 
compiler output abailable. 

C152I VERB NUMBER NOT FOUND 

Explanation : The verb number specified on a line-control card 
does not exist on the card specified. 

Action: The nearest verb number on the card specified is used. 

Programmer Response : Probable user error. Correct verb number 
specification before reexecuting. 

If the problem recurs, do the following before calling IBM 
for programming support: have source deck, control cards, and 
compiler output available. 

C153I NO ROOM TO DUMP. 

Explanation : If this message immediately follows a 
program-control card, sufficient storage is not available for 
the debug subroutine or for the 72 bytes of data required for 
each program in the run unit. If this message follows an 
abnormal termination message, one or more of the following is 
not available in free storage or in the COBOL Procedure 
Division: a contiguous block of 4000 bytes, a contiguous block 
of 1800 bytes, or a contiguous block of 512 bytes. 

Action; No Data Division dump for the indicated program and, 
in some instances, no statement number information, is 
provided. 

Progr amme r Response : Probable user error. Increase the size 
of the partition before reexecuting. See "System 
Configuration" for information about storage requirements for 
symbolic debugging. 

If the problem recurs, do the following before calling IBM 
for programim.ing support: have source deck, control cards, and 
compiler output available- 
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C15UI I/O ERROR ON DEBUG FILE. 

Explanation ; An input/output error has occurred on the debug 
file. Note that such an error may be the result of a file 
other than the debug file being mounted on the logical unit 
specified. 

Action: SYKDMP output is cancelled for the indicated program. 

Response : Hardware, operator, or user JCL error. Before 
reexecuting, check logical unit number specified on 
program-control card against current mounting, as well as the 
ASSGN, DLBL, and EXTENT cards of compilation. 

If the problem recurs, do the following before calling IBM 
for programming support: have source deck, control cards, and 
compiler output available. 

C155I WRONG DEBUG FILE FOR PROGRAM. 

Explanation ; The file corresponding to the filename and/or 
logical unit number provided on the program-control card is not 
the debug file created for this program at compile time. 

Action: SYMDMP output is cancelled for the indicated program. 

Programmer Response : Probable user error. Before reexecuting, 
ensure that the filename and/or logical unit specified on the 
program-control card corresponds to that of the debug file 
created at compile time. 

If the problem recurs, do the following before calling IBM 
for programming support; have source deck, control cards, and 
compiler output available. 

C156I NO ROOM FOR DYNAMIC DUMP. 

Explanation ; Sufficient storage is not available to store the 
line-control card information during execution. 

Action ; Dynamic dumping is cancelled for the indicated 
program. 

Programmer Response : Probable user error. Increase size of 
partition or decrease number of line-control cards before 
reexecuting. 

If the problem recurs, do the following before calling IBM 
for programming support; have source deck, control cards, and 
compiler output available- 
CIS? I INVALID FILENAME. 

Explanation ; If the "filename" parameter is specified for a 
disk file on the CBL card at compile time, the same "filename" 
must also be specified on the program>-control card. "Filename" 
may be from one to seven characters in length; the first 
character must be a letter. 

Action; All SYMDMP output is cancelled for the indicated 
program. 

Programmer Response ; Probable user error. Correct "filename" 
specification on the program-control card before reexecuting. 

If the problem recurs, do the following before calling IBM 
for programming support: have source deck, control cards, and 
compiler output available. 
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C158I INVALID LOGICAL UNIT. 

Explanation ; The logical unit parameter on the program-control 
card must be specified, must be an integer between and 244, 
and must match the one specified in the ASSGN control statement 
for the debug at compile time. 

Action : All SYMDMP output is cancelled for the indicated 
program- 

Proqrammer Response ; Probable user error. Correct logical 
unit specification on program-control card before reexecuting- 

If the problem, recurs, do the follov^in'^ before callinQ IBM 
for programming support; have source deck, control cards, and 
compiler output available. 

C159I MISSING PARAMETERS. 

Explanation ; A non-continued line-control card ends with 
(HEX) , OF, IN, or THRU. Possibly a continuation punch is 
missing in colum.n 72- 

Action: A HEX or THRU option ending a card is ignored. When a 
card ends with OF or IN, the word is ignored and the identifier 
that is dumped is the first one encountered whose qualifiers 
match those preceding the word OF or IN. 

Programmer Response ; Probable user error. Check line-control 
card for keypunch errors before reexecuting. 

If the problem recurs, do the following before calling IBM 
for programming support; have source deck, control cards, and 
compiler output available. 

C160I INVALID OPTION- 

Explanation ; An element used as an optional parameter on a 
program-control card is not one of the legal program-control 
card options - 

Action ; The element is ignored. 

Programmer Response ; Probable user error. Correct syntax of 
program-control card before reexecuting. 

If the problem recurs, do the following before calling IBM 
for programming support; have source deck, control cards, and 
compiler output available. 

C161I SUBSCRIPTING ILLEGAL. 

Explanation : The "name" parameter of the line-control card may 
not be subscripted. 

Action : The subscripts are ignored. Every occurrence of the 
identifier is dumped- 

Proqrammer Response ; Probable user error. Specify the name of 
the item without the subscript before reexecuting. This will 
result in a dump of every occurrence of the item. 

If the problem recurs, do the following before calling IBM 
for programming support; have source deck, control cards, and 
compiler output available. 
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C16 2I ON PARAMETER TOO BIG, 

Explanation ; Neither the n, iti, nor k parameter of the ON 
option may exceed 32767. 

Action ; The number is reduced to 32767. 

Programmer Response : Probable user error. Correct invalid 
parameter before reexecuting. 

If the problem recurs, do the following before calling IBM 
for programming support; have source deck, control cards, and 
compiler output available. 

C163I FLOW TRACE NON-CONTIGUOUS. MORE THAN 10 PROGRAMS ENCOUNTERED 

Explanation ; A non-contiguous flow trace will result if FLOW 
option is effective in a subprogram structure of more than 10 
programs compiled with the FLOW option. 

Action; The FLOW trace is terminated upon encountering the 
eleventh PROGRAM-ID. Tracing resumes only upon returning to 
one of the original ten programs. 

Programmer Response ; Probable user error. If trace is absent 
for a program where it is critical, recompile one or more of 
the programs where the flow is non-critical without the FLOW 
option and reexecute. 

If the problem recurs, do the following before calling IBM 
for programming support; have source deck, control cards, and 
compiler output available - 

C164I FLOW TRACE IN EFFECT BUT NO PROCEDURES TRACED. 

Explanation ; Abnormal termination has taken place before any 
COBOL statement with a procedure-name has been traced. 

Action ; No tracing is done. 

Programmer Response ; Probable user error. If trace is 
desired, recompile the program after inserting additional 
procedure-names . 

If the problem recurs, do the following before calling IBM 
for progromming support; have source deck^ control cards, and 
compiler output available. 

C165I SYMDMP/STATE/FLOW/COUNT INTERNAL ERROR. EXECUTION CANCELLED. 

Explanation ; Abnormal termination occurred during execution of 
one of the debugging subroutines - 

Action; The job is cancelled. 

Programmer Response ; Internal logic error. 

If the problem recurs, do the following before calling IBM 
for program.ming support; have source deck, control cards, and 
compiler output available. 
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C169I STATE OPTION CANCELLED. 

Explanation ; compiler or logic error has occurred during STATE 
option processing. Under certain conditions, this error may 
result from other user errors. For example, a loop might 
destroy some of the information required by the STATE 
subroutines; an invalid branch might cause a non-existent 
priority- number to be stored in the TGT, etc. 

Action: STATE output is cancelled. 

Programmer Response ; Probable user error. Possible compiler 
error or user error. Correct other known errors (if any) 
before attempting reexecution. 

If the problem recurs, do the following before calling IBM 
for programming support: have source deck, control cards, and 
compiler output available. 

C170I INVALID ADDRESS. 

Explanation ; The address calculated for a subscripted 
identifier^ or a starting or ending address of a 
variable-length identifier used as the receiving field in a 
MOVE statement is invalid. 

Action ; A symbolic dump is produced. 

Programmer Response ; Probable user error. Possible compiler 
error or user error. Correct other known errors (if any) 
before attempting reexecution. 

If the problem recurs, do the following before calling IBM 
for programming support; have source deck, control cards, and 
compiler output available, 

C171I SPACE NOT FOUND FOR THE COUNT CHAIN. CONTINUING. 

Explanation ; A GETVIS m.acro was unsuccessful due to lack of 
space. 

Action; Execution continues. Execution statistics are not 
provided for the last indicated program unit. 

Programmer Response : Probable user error. Allocate more space 
on EXEC card before attempting reexecution. 

If the problem recurs, do the following before calling IBM 
for programming support; have source deck„ control cards, and 
compiler output available. 

C172I SPACE NOT FOUND FOR THE VERBSUM TABLE. CONTINUING. 

Explanation ; A GETVIS macro was unsuccessful due to lack of 
space. 

Action; Execution continues. Verb summary statistics are not 
provided for the program. 

Programmer Response : Probable user error. Allocate more space 
on EXEC card before attempting reexecution. 

C173I FREEVIS FAILED. EXECUTION CANCELLED. 

Explanation ; A FREEVIS macro was unsuccessful. 

Action; Execution is terminated. 
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Proqranimer Response ; Probable user error. Allocate more space 
on EXEC card before attempting reexecution. 

If the problem recurs, do the follov?ing before calling IBiy! 
for prograirming support: have source deck, control cards, and 
compiler output available. 

C175I INVALID COUNT TABLE ENTRY. EXECUTION CANCELLED. 

Explanation ; A count table entry in the object module is not 
one of the following; end-of -table indicator, procedure-id, or 

verb-id. 

Action: Execution is terminated. 

Programmer Response : Probable user error. Possible compiler 
or user error. Check your program for routines that may have 
moved data into the count table area. Correct other known 
errors (if any) before attempting execution. 

If the problem recurs, do the following before calling IBM 
for programming support: have source deck, control cards, and 
compiler output available. 



COBOL OBJECT PROGRAM UNNUMBERED MESSAGES 



Explanation ; This message is written on the console and is 
recognizable because it is not preceded by a message code and 
action indicator. It is issued by an object program originally 
coded in COBOL - The message text is supplied by the object 
program and may indicate alternative action to be taken. 

System Action : The job continues. 

Operator Response : Operator response, if any is needed, is 
determined by the message text. 
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APPENDIX J: COBOL 3886 OPTICAL CHARACTEE READER SUPPORT 



This appendix contains information on 
the 3886 Optical Character Reader, Model 1* 
(denoted as "the OCR"). Topics discussed 
include: 

3886 OCR processing 

COBOL considerations for 3886 OCR 

processiuy . 
Status key values 
Sample program 

This discussion assumes familiarity with 
these IBM 3886 Optical Character Reader 
publications: 

IBM 3886 OCR General Information Manual , 
Order No. GA21-9146 — for terminology, 
device capabilities, and the formats of 
the header and data records. 

IBM 3886 OCR Input Document Design and 
Specifications , Order No, GA21-9148 — 
for document design considerations and 
detailed specifications. 

In addition, the applicable portions of the 
following manuals should be referenced: 

IBM DOS/TS Supervisor and I/O Macros , 
Order No. GC33-5373 — for describing 
documents using the DFR and DLINT 
macros. 

IBM DOS/VS System Generation , Order 
No. GC33-5377 

IBM DOS/TS Data Management Guide , Order 
No. GC24-5062. 

IBM DOS/VS Program Planning Guide for 
the IBM 3886 Optical Character Reader, 
Model 1 , Order No. GC21-5059 



3886 OCR PROCESSING 



The 3886 OCR, Model 1 is a general 
purpose online device that satisfies a 
broad range of data entry reguirements, 
The OCR accepts documents sized from 3 
inches by 3 inches to 9 inches by 12 
inches. It can read machine-printed 



alphabetic characters, numeric characters, 
and certain special characters in a wide 
variety of fonts, as well as hand-printed 
numeric characters. 

The OCR reads documents one line at a 
time, under program control. Additional 
features, all under program, control, 
include: 

• document marking 

• line marking 

• document eject (with stacker selection) 

• line reread (for the current line, and 
with a different format if desired) 

Note: The OCR cannot read previous lines; 
reading can proceed from top to bottom on 
the document only . 



IMPLEMENTING AN OCR OPERATION 



♦This device should not be confused with 
the 3886, Model 2- an offline Optical 
Character Reader with output to tape. 
Information is included in this chapter on 
processing the tapes produced by the Model 
2. 



Document Design 



The OCR form that will be used for input 
should be prepared independently of the 
COBOL program. Document design criteria 
are described in detail in IBM 3886 Optical 
Character Reader, Input Document Design 
Guide and Specifications . 

The most important aspects of document 
design are: 

1. The locations of lines which can be 
read. These lines are identified by 
"timing marks." Lines not associated 
with timing marks are always ignored 
by the OCR. Note that lines may be 
almost anywhere on the document, and 
need not be at regular intervals. 

2. The location of fields to be read. 
Fields, (strings of related 
characters) should be identified in 
document design. They should be 
described using the DFR and DLINT 
macros. (See section entitled 
"Document Description".) 

3. The form identifier. This field 
should be a pre-printed code at a 
common location on the first readable 
line of each format. This field can 
be ignored by programming or DLINIT 
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specification if desired; it should, 
however, be included in the form 
design so as to allow for later form 
changes or intermixing of forms in 
batches without disruption of 
operations. 



Document Description 



Documents are described in the system 
with the Define Format Record (DFR) and 
Define Line Type (DLIHT) macros. These 
macros should be coded independently of the 
COBOL program. 

The DFR macro identifies, by name, a 
collection of DLINT macros, and establishes 
various default field scanning options for 
them. Each different DFR grouping 
identifies a different document, or a 
largely different way of scanning the same 
document (for example, a document in a 
different font) . 

DFR and DLINT macros, after assembly and 
linkage editing, are preserved in loadable 
form until called for by the application 
program . 

Each DLINT macro describes the scanning 
of a line, by field, in terms of 

1. The starting and ending points of 
fields on a line (in tenths of an 
inch) . 

2. The field lengths (in characters) . 

3. The font code to be used (OCR-A, 
OCR-B, Gothic, or hand-printed 
numerics, all with various additional 
options) . 

4. Field editing (blank fill, blank 
suppression, zero fill, left or right 
justification, special character 
suppression) . 

5. Field character delimiters (a 
character to end a field scan) . 

Note that the DLINT macro may specify 
either standard mode or image mode. In 
standard mode, all DLINT options are valid, 
and the data record is of a fixed format, 
according to the field lengths in 
characters. In image mode, the field 
length and all EDIT keywords are invalid. 
The data record begins with Itt parameters, 
each two bytes long, indicating the length 
of the fields that follow. Because of this 
variable format in the data record, it is 
recommended that image mode be used only in 
applications for which standard mode is 
unsuitable. 



COBOL Support 



COBOL supports the OCR with a subprogram 
(invoked by CALL statements) , Data Division 
COPY statement library material (to fully 
describe the parameter area reguired by the 
subprogram) , and Procedure Division COPY 
statement library material (to provide 
procedures that simplify invocation of the 
subprogram) . 



File Description 



The file is described by the Data 
Division COPY statement member. (See 
sample program for format.) All fields and 
codes are included, with descriptive names 
and default values. The programmer need 
only modify those fields that are not 
appropriate for the application . 

The file description ("OCR-FILE" in the 
COPY statement member) includes all fields 
that the programmer must provide to the 
subprogram, the OCR-STATOS-KEY returned by 
the subprogram, and fields that describe 
the header and data records returned by the 
device. Note that the file is described 
through data records rather than the usual 
COBOL FD. 



Note; 



The header and data records are not 



constructed under program control and are 
not altered after reading. Their contents 
are fully described in IBH 3886 Optical 
Character Reader General Information 
Manual. 



Record Description 



The COBOL record descriptions are based 
on the DLINT formats, either in image mode 
or in standard mode. 

If standard mode scanning is specified, 
the data record is returned in a fixed 
format according to the DLINT macro; that 
is, contiguous fields, from left to right, 
in the same order as in the DLINT macro, 
each with a specified length in bytes. If 
image mode scanning is specified, however, 
the field lengths are returned at the 
beginning of the data record. 

The programmer may describe the data 
records to be read by the application 
program by following the Data Division COPY 
statement request with statement (s) of the 
form : 

05 dataname REDEFINES OCR-DATA-RECORD 
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The structure of each record description 
should follow each such statement starting 
with a level number greater than 5. (See 
sample program for example.) 



Procedura 1 Code 



01 OCR-PILE. 

05 OCR-riLE-CONTEOL-AREA 

10 OCR-FILE-ID PIC X (8) VALUE 
•SYSnnn'. 
(Unique file name; also, must 
agree with JCL ASSGN 
statement) 



The COBOL source statements control the 
file, read lines, and recover from errors. 
The subprogram CALL statement requirements 
are described in the Procedure Division 



— _i . 
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provides paragraphs which the COBOL 
programmer can PERFORM to set the proper 
operation code, CALL the subprogram, and 
pass control to a programmer-supplied 
exception routine if an exception occurs. 
The programmer should COPY these paragraphs 
into his program. 

The programmer must move parameter 
information to the file area 
(OCR-FILE-CONTROL-AREA) , and then issue a 
PERFORM statement for the appropriate 
procedure. 

If an exception occurs, the COPY 
statement member passes control to the 
procedure-name OCR-EXCEPTION-ROUTINE. If 
operations are to be retried in this 
routine, the programmer should issue the 
appropriate CALL (not PERFORM) statement 
and test the OCR-STATDS-KEY value 
afterwards. 

Return from the OCR-EXCEPTION-ROUTINE 
would normally be to OCR-CALL-EXIT (after a 
successful retry or recovery) . Control is 
then returned to the invoking PERFORM 
statement. 



JCL Considerations 



Programs using the IBM-supplied 3886 
processing subroutines must have a SIZE 
parameter specified on the EXEC card and 
cannot run in REAL mode. The user must 
specify the SIZE parameter equal to the 
size of his problem program to free the 
remainder of his partition for use as the 
page pool. Each opened 3886 file requires 
at least 2K bytes of the page pool. 



Subprogram Interface 



The IBM-supplied COPY menbers provide a 
data area (»OCR-FILE») and CALL statements 
using this area for parameter interface to 
the OCR subprogram. The data area has the 
following format: 



10 OCR -FORMAT -RECORD-ID PIC X (8) 
VALUE "XXXXXXXX". 

(DFR phase name, used for 
'OPEN* or "SETDV") 

10 OCR-OPERATION PIC X (5) . 

("OPEN", "CLOSE", "READ", 
"READO", "WAIT", "SETDV", 
"MARKL", "MARKD", or "EJECT" 
(left justified) . 

10 OCR-STATUS-KEY PIC 99. 

(also referred to as exception 
code.) 

10 OCR-LINE 

15 OCE-LINE-NUMBER PIC 99. 

(Line number (0-33) passed 
to "MARKL", "BEAD", or 
"EJECT") 

15 OCR-LINE-FORMAT PIC 99. 

(Line format number (0-63) 
passed to "READ") 

10 OCR-BARK PIC 99. 

(Mark option (1-15) passed to 
"MARKL" or "MARKD".) 

10 OCR-STACKER PIC 9. 

(Pocket number (1-2) passed to 
"EJECT".) 

05 OCR-HEADER-RECORD PIC X (20) . 

(Header information returned from 
"READ" or "WAIT".) 

05 OCR-DATA-RECORD PIC X(130). 

(Data record returned from "READ" 
or "WAIT".) 

(For descriptions of these operations, see 
the section "Statements for Invoking 3886 
I/O Functions".) 



Note : If the CALL statement does not have 
one, and only one, parameter following the 
USING option, the subprogram will return 
control immediately to the user (with a 
value of 8 in register 15) . No error 
indication will be available through COBOL. 

Table 37 contains OCR status key values 
and their meanings. Table 38 is a guide to 
which operations cause status key values 00 
through 99. Table 39 supplies the user 
responses to status key values. 
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Table 37. OCR Status Key Values and User Actions 

I I 



Status Key 
Code 



Meaning 



00 
10 
3x 



9y 



Successful completion 

End-of-file* 

I/O error or related error where r^ 
X = 1 — Mark Check 

= 2 — Nonrecovery 

=3 — Inconplete Scan 

=4 — Mark Check and Equipment Check 

=9 — Permanent Error 

Other error where: 

y = 2 — logic error, that is, file not open (except OPEN) , file already 
open (for OPEN), WAIT issued, but no READO pending, WAIT not 
issued for pending READO. 
=3 — insufficient storage available (OPEN) or failure in storage 

release (CLOSE) 
=5 — invalid parameter (other than operation code) 
=9 — unrecognizable operation code 



^The end-of-file condition is raised after the listed I/O commands if: 

— the operator has pressed the END-OF-FILE button, and 

— no documents remain in the read station, and 

— no errors are outstanding 

If // ASSGN SYSxxx,IGN has been specified, EOF is given only on READ and WAIT 
commands. While the end-of-file condition is active, commands (other than CLOSE) are 
only checked for validity. 
2lf any I-O errors, or certain system errors occur during the OPEN operation, the job 
is canceled by the system. 



Table 38. Possible Status Key Values, By Operation 



, p , 

1 OCR-OPERATION 1 
1 Value 1 


n 


, 


■1 


1 






• -■ ■\ 






r- 


■ 1 


1 


lOCR-STATOS-KEY 
[Possible Value 


1 
lOPEN 


CLOSE 


READ 


READO 


WAIT 


MARKL 


MARKD 


EJECT 


SETDV 


other 1 


1 00 


1 X 


X 


X 


X 


X 


X 




X 




X 




X 




1 10 






X 




X 


X 


X 




X 




X 






1 31 


















X 










1 32 






X 


X 


X 


X 




X 




X 




X 




1 33 






X 




X 


















1 34 




















X 








1 39 






X 


X 


X 


X 




X 




X 




X 




1 92 


i X 


X 


X 


X 


X 


X 




X 




X 




X 




1 93 


I X 


























1 95 


1 X 




X 


X 




X 




X 




X 








1 99 


























X 1 
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Table 39. Oser Responses to Status Key 



I 1 

Status Key | Meaning 



Response 



00 
10 



31 


Hark Check 


32 


Nonrecovery Error 


33 


Incomplete Scan 



34 



39 



92 



93 



95 



99 



Successful (no EOF) 
End-of-file 



Mark Check and 
Equipment Check 

Permanent Error 



Logic error 



Insufficient storage 



Invalid parameter 



Unrecognizable 
operation 



The operation has completed properly. 

Do EOF processing and close the file, or have 
operator ready 3886 and continue processing. See 
Note 1. 

Attempt to reread the line, or eject document and 
prepare to process next document. 

Eject document and prepare to process next document. 

Reread the line using a different DLINT, or using an 
image-mode DFS. 

See Note 2. 



See Note 2. One of the following has occurred: 
Command Reject, Bus Out Check, Equipment Check, 
Non-Initialized, RCP error, or Invalid Format. 

See Note 3. One of the following operation order 
errors has occurred: 

— OPEN issued on file already open 

— file not open {all operations except OPEN) 

— WAIT issued but no READO in progress 

— READO not followed by WAIT 

See Note 3. The GETVIS issued by the COBOL 
subroutine has failed. Check that the SIZE 
parameter is large enough. 

See Note 3. A parameter required by the last 
operation was invalid (too large, too small, or 
contained invalid characters) . 

See Note 3. The OCR-OPERATION parameter contained 
an illegal operation code. 



Notes : 

1. Serious I-O error conditions exist. No more I/O should be performed on the device 
after any of these errors are encountered. The program should indicate the error, 
perform error recovery, and issue a STOP RDN. 

2. A serious programming error has occurred, or there is a problem in the program 
environment. The program should indicate the error, perform clean-up, and issue a 
STOP RDN. 

3. WAIT and READ commands return data and header records only for the following 
codes: 00, 10, 31, and 33. For other codes, the contents of the header and data 
record areas are unpredictable. 
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STATEMENTS FOR INVOKING 38 86 I/O FUNCTIONS 



READO Function (Equivalent to DOS BEAD 
Macro) 



OPEN Function (Equivalent to OPEN Hacro) 



OPEN makes a logical file available to 
your program and loads the appropriate 
format record into the 3886. The statement 
format for OPEN is: 



PERFORM OCR-OPEN 



The subprogram requires these fields: 
OCR-FILE-ID, OCR-OPERATION ('OPEN ») , 
OCR-FORBAT-RECORD-ID 



The subprogram will return: OCR-STATUS-KEY 



READO (read overlapped) initiates the 
reading of one line of data from the 
document, WAIT must subsequently be issued 
to complete the request. The statement 
format for READO is: 

PERFORM-OCR-READ-OVERLAPPED 

The subprogram requires these fields: 
OCR-FILE-ID, OCR-OPERATION ('READO*), 
OCR-LINE-NDMBER, OCR -LINE-FORMAT 

The subprogram will return: OCR-STATUS^KEY 

Note : A successful READO function must be 
followed by a WAIT request for that same 
OCR-FILE area. No intervening I/O 
operations for that file are allowed. 



CLOSE Function (Equivalent to DOS CLOSE 
Macro) 



CLOSE deactivates any 3886 files used by 
your program. These files must be closed 
before the program can be terminated. The 
statement format for CLOSE is: 



WAIT Function (Equivalent to DOS WAITF 
Hacro) 



WAIT completes the action of the 
preceding READ. The statement format for 
WAIT is: 

PERFORM OCR-READ 



PERFORM OCR-CLOSE 

The subprogram requires these fields: 
OCR-FILE-ID, OCR-OPERATION ('CLOSE') 

The subprogram will return: OCR-STATUS-KEY 



READ Function (Equivalent to DOS READ and 
WAITF Macros) 



READ allows one line of data to be read 
from the document. The statement format 
for READ is: 

PERFORM OCR-READ 

The subprogram requires these fields: 
OCR-FILE-ID, OCR-OPERATION ('READ'), 
OCR-LINE-NOMBER, OCR-LINE-FORMAT 

The subprogram will return: 
OCR-STATDS-KEY, OCR-HEADER -RECORD , 
OCR-DATA-RECORD 



Note: The READ function combines the 
functions of READO and WAIT. I/O overlap 
is not allowed within the issuinq task. 



The subprogram requires these fields: 
OCR-FILE-ID, OCR-OPERATION ('WAIT') , 

The subprogram will return: 
OCR-STATUS-KEY, OCR -HEADER-RECORD, 
OCR-DATA-RECORD 

The WAIT function causes the active task 
to be placed in the WAIT condition, if 
necessary, until the preceding READO 
operation is completed. It must be issued 
only after a successful READO, with no 
intervening commands for that file. 



HARKL Function (Equivalent to DOS CNTBL 
Macro with LHK Option) 



MARKL is used to mark a line on the 
document. The statement format for HARKL 
is: 

PERFORM OCR-HARK-LINE 

The subprogram requires these fields: 
OCR-FILE-ID, OCR-OPERATION ('MARKL'), 
OCR-LINE-NOMBER, OCR-MARK 

The subproqram will return: OCR-STATUS-KEY 
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HABKD Function (Equivalent to DOS CNTRL 
Macro with DMK Option) 



HfiEKD is used to mark the document (in 
the Page Mark location) . 

The statement format for MARKD is: 

PERFORM OCR-MARK-DOCUMENT 

The subprogram reguires these fields: 
OCR-FILE-ID, OCR-OPERATION ('MARKD*) f 
OCS-nSRK 



SETDY (Set Device by Loading a Format 
Record) Function (Eguivalent to DOS SETDEY 
Macro) 



SETDV allows format records to be 
changed during execution of the program, 
The statement format for SETDV is: 

PERFORM OCR-SET-DEVICE 

The subprogram reguires these fields: 
OCR-FILE-ID, OCR -OPERATION (»SETDV») , 
OCR-FORMAT-RECORD-ID 



The subprogram will return: OCR-STATDS-KEY ^^e subprogram will return: OCR-STATUS-KEY 



EJECT Function (Eguivalent to DOS CNTRL 
Macro, with ESP Option) 



EJECT is used to eject the document into 
a specified stacker, with optional 
validation of its total number of timing 
marks. The statement format for EJECT is: 

PERFORM OCR-EJECT 

The subprogram reguires these fields: 
OCE-FILE-ID, OCR-OPERATION (» EJECT ») , 
OCR-STACKER, OCR-LINE-NUMBER 

The subprogram will return: OCE-STATUS-KEY 



COBOL 3886 Library Routine 

The COBOL 3886 library routine is 
invoked in response to the CALL statement. 
For the proper execution of this routine 
GETVIS=YES must be specified at system 
generation. An illegal SVC results if 
GETVIS=NO is specified. 

Table 40 contains a list of CALL 
statements used for invoking 3886 I/O 
functions (if the IBM-supplied COPY member 
is not used) . 

All OCR CALL statements have the format 
CALL *ILBDOCR0» USING OCR-FILE, where 
OCR-FILE is used as follows: 
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Table 40. CALL Statements for Invoking 3886 I/O Functions 



1 ■■ ' ■ 

I Function 


■ - - ■ - ' — 1 




1 


1 (OCR-OPERATION) 


Set by User 


Subroutine Returns 




1 OPEN 


OCR-FILE-ID 

OCR-OPERATION 

OCR -FORM AT-RECOFD-ID 


OCR-STATUS-KEY 




1 CLOSE 


OCR-FILE-ID 
OCR-OPERATION 


OCR-STATDS-KEY 




1 READ 


OCR-FILE-ID 








OCR-OPERATION 


OCR-STATUS-KEY 






OCR-LINE-NUMBER 


OCR-HEADER -RECORD 






OCR-LINE-FORHAT 


OCR-DATA-RECORD 




1 READO 


OCR-FILE-ID 








OCR-OPERATION 


OCR-STATUS-KEY 






OCR-LINE-NDMBER 








OCR-LINE-FORMAT 






1 WAIT 


OCR-FILE-ID 


OCR-STATUS-KEY 






OCR-OPERATION 


OCR-HEADER-RECOED 
OCR-DATA-RECORD 




1 MARKL 


OCR-FILE-ID 








OCR-OPERATION 


OCR-STATUS-KEY 






OCR-LINE-NUMBER 








OCR -MARK 






1 MARKD 


OCR-FILE-ID 








OCR-OPERATION 


OCR-STATUS-KEY 






OCE-LINE-NUSBER 








OCR-MARK 






1 EJECT 


OCR-FILE-ID 








OCR-OPERATION 


OCR-STATUS-KEY 






OCR-LINE-NUMBER 








OCR-STACKER 






1 SETDV 


OCR-FILE-ID 








OCR-FORMAT-RECORD-ID 


OCR-STATUS-KEY 






OCR-OPERATION 







PROCESSING TAPES FROM THE OCR 3886, MODEL 2 



Tape records produced from the IBM 3886, 
Model 2 are almost identical in format to 
the header and data records returned by the 
Model 1 . The main differences between the 
records are; 



Model 2 tapes contain a document 
trailer record after the line output 
records for each document. The content 
of this trailer record differs from 
that of line output records. 

The codes used in certain fields of the 
header record differ between the two 
models . 



Because of 
Data Division 
for the Model 
the Model 2 t 
punch out the 
it according 
requirements, 
statement mem 
data record, 
file. 



the similarity, h 
COPY statement me 
1 may be tailored 

ape records. To d 
COPY statement me 

to the installatio 
and recatalog it. 

ber may then be in 

under an FD for th 



owever, the 
mber defined 
to describe 
o this, 
mber, modify 
n 

The COPY 
eluded as a 
e input tape 



Specific information on the formats and 
contents of the Model 2 tape records is 
contained in IBM 3886 Optical Character 
Reader, General Information Manual . 
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CEL LIB 
00001 
C0002 
00003 
OCOOU 
00005 
C0006 
00007 
00008 
00009 
00010 
00011 
00012 
00013 
00014 
00015 
00016 
00017 
00018 
00019 
00020 
00021 
00022 
00023 
00024 
00025 
00026 
00027 
00028 
00029 
00030 
00031 
00032 
00033 
00034 
00035 
00036 
00037 
00038 
00039 
00040 C 



lt1tiF:4f^f:*t:ti^^:1c***it:tfdt:iLJlF^i^:ipiflL-^ifitf:t*****iF ************************** 

********* SAMPLE OCR PROGRAK *** 

****:i: ********** ***ilf***ilf *********** ***iii:^* ********* *****•!:***** 

IDENTIFICATION DIVISION 
PR0GRA^5-ID. SAMPLE 
*♦** + + rj.Hxs PROGRAM IS THE COEOL EQUIVALENT OF THE 

* ASSEMBLY LANGUAGE SAKPLE PROGRAM 'DOCLIST', 

* CONTAINED IN THE DOS/VS PROGRAM PLANNING GUIDE 

* FOR THE IBM 3886 OPTICAL CHARACTER READER, MODEL 1 

* (ORDER NO. GC21-5059) 
ENVIRONMENT DIVISION. 
INPUT-OUTPUT SECTION. 
FILE-CONTROL . 

SELECT PRINTER, ASSIGN TO SYS009-UR-1403-S. 
DATA DIVISION. 
FILE SECTION, 

FD PRINTER LABEL RECORDS ARE OMITTED. 
01 PRINT-RECORD. 

05 FILLER PIC X. 

05 PRINT-LINE PIC X(130). 
WORKING-STORAGE SECTION. 
77 PRINT-CONTROL PIC 9 

77 MSG- PERMANENT- ERROR PIC X(24) 

• PERMANENT ERROR OCCURRED ' . 
77 MSG-MARK- CHECK PIC X(19> 

'MARK CHECK OCCURRED 
77 MSG-MARK-AND-EQUIP-CHECK PIC X{39) 



VALUE 1. 
VALUE 



VALUE 



VALUE 



77 



77 



77 



01 



'MARK CHECK AND EQUIPMENT CHECK OCCURRED'. 

VALUE 



MSG-INCOMPLETE-SCAN PIC X{24) 

• INCOMPLETE SCAN OCCURRED ' . 
MSG-NONRECOVERY-ERROR PIC X(26) 

' NONRECOVERY ERROR OCCURRED ' . 
MSG-BAD-DATA PIC X(50) 

•THE FOLLOWING LINE WAS MISREAD. 
MSG-TERMINATION , 
05 FILLER PIC X(44) 

•TERMINAL ERROR OCCURRED - OCR- STATUS-KEY 

MSG-TERM- STATUS-KEY PIC XX. 



VALUE 



VALUE 
THE LINE HEADER 



VALUE 



05 

01 OCR-FILE COPY ILEDOCRB. 
:»«*«:|.*4t* ILBDOCRD - OCR DATA DESCRIPTION 



♦♦****91547000 

******91548000 

******91549000 

91550000 

91551200 
91551400 
91551600 
91551800 
91551900 
91552000 
91552200 
91552400 
91552600 
91553000 
91553200 
91553400 
91553600 
91553800 
91553900 
91554000 
91554200 
91555000 
91556000 
91556100 
91556200 
91556600 
91556700 
91556800 
91556900 
91557000 
91557200 
91557400 
91557600 
91557700 
91557800 
91558100 
91558300 
91558400 



************************* 



Figure 69. Sample OCR Program (Part 1 of 5) 
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00041 C 

00042 C 

00043 C 



^i^d^tjH::^^dl:i^H:td^it:4:**^**J^****iH:if ***************************** ********** 

*****♦♦+ OCR 3886 FILE FORt^J^T ********** 

****************************************************************** 



GC045 
00046 
00047 
00048 
00049 
00050 
00051 
00052 
00053 
00054 
00055 
00056 
00057 
00058 
00059 
00060 
00061 
00062 
00063 
00064 
00065 
00066 
00067 
00068 
00069 
00070 
00071 
00072 
00073 
00074 
00075 
00076 
00C77 
00078 
00079 
00080 
00081 
00082 
00083 
00084 
00085 
C0C86 
00087 
00088 
00089 
00090 
00091 
00092 
00093 
00094 
00095 
00096 
00097 
00098 
00099 
00100 
00101 
0C102 
00103 
00104 
00105 
00106 
00107 
00108 
00109 
00110 
00111 
00112 
00113 
00114 
00115 
00116 
00117 
00118 
00119 
0C120 
C0121 
00122 



05 CC3 
10 
10 
10 



10 



10 



10 
10 



******* 

FILLED 
(NOTE 



-FILE-COMTROL-ASIA . 

OCR-FILE- ID PIC X(8) VALUE 'SYSOIO ", 

OCR-FORMAT-RECORD-ID PIC X(8) VALUE 'FRLGDFRl'. 

OCR-OPERATION PIC X(5) VALUE 'OPEN '. 

88 OCRO-CPEN VALUE 'OPEN '. 

88 OCRO-CLOSE VALUE 'CLOSE*. 

88 OCRO-READ VALUE 'READ '. 

88 OCRO-READ-OVERLAPPED VALUE 'RSADO'. 

88 OCRO-WAIT VALUE "WAIT '. 

88 OCRO-MARK-LINE VALUE 'MARKL'. 

88 OCRO-MARK-DOCUMENT VALUE 'iVlARKD'. 

88 OCRO-EJECT VALUE "EJECT*. 

88 OCRO-SETDEV VALUE "SETDV. 

CCR-STATUS-KEY PIC 99 VALUE 0. 

88 OCRS-SUCCESSFUL VALUE 00. 

88 OCRS-END-OF-FILE VALUE 10. 

88 OCRS-IO-ERRORS VALUE 30 THRU 39, 

88 OCRS-^^ISC-ERROR VALUE 30. 

88 OCRS-MARK-CHECK VALUE 31. 

88 OCRS-NONRECOVERY-ERROR VALUE 32. 

88 OCRS-INCOMPLETE-SCAN VALUE 33. 

88 OCRS-MARK-AND-EQUIP-CHECK VALUE 34. 

88 OCRS-PERKANENT-ERPOR VALUE 39. 

88 OCRS-SPECIAL-ERRORS VALUE 90 THRU 99 

88 OCRS-LOGIC-ERROR VALUE 92. 

88 OCRS-RESOURCE-UNA VAILAELE VALUE 93. 

88 OCRS-INVALID-PARAMETER VALUE 95. 

88 OCRS-INVALID-OPERATION VALUE 99. 
OCR-LINE. 

15 OCR-LINE-NUKBER PIC 99 VALUE 1. 

15 OCR-LINE-FORMAT PIC 99 VALUE 1.' 

OCR-MARK PIC 99 VALUE 0. 

OCR-STACKER PIC 9 VALUE 1. 

HEADER AND DATA RECORD AREAS **♦♦*** 

IN BY SUCCESSFUL 'READ' AND/OR 'WAIT'. 

•READO' DOES NOT ALTER THESE AREAS) 



05 



VALUE ZEROS. 



10 
10 
10 



PIC 
PIC 
PIC 
PIC 



99. 
99. 

9. 

9. 



10 



88 
88 



VALUE 
VALUE 
VALUE 
VALUE 
VALUE 
VALUE 
VALUE 
VALUE 

OCCURS 14. 
VALUE 
VALUE 
VALUE 
VALUE 
VALUE 
VALUE 



0. 
1. 
3. 
2. 
4. 
6. 
7. 
5. 



OCR-HEADER-RECORD 
10 OCRH-LINE-NUMBER 
CCRH-LINE-FORMAT 
OCRH-LINE-SCAN-COUNT 
OCRH-LINE-STATUS 
88 OCRH-LINE-GOOD 
88 OCRH-LINE-BLANK 
88 OCRH-LINE-GROUP-ERASE 
88 OCRH-LINE-CRITICAL-ERR 
88 OCRH-LINE-NON-CRITICAL-ERR 
88 OCRH-LINE-COMBINED-ERE 
88 OCRH-LINE- INVALID 
88 OCRH-END-OF-PAGE 
OCRH-FIELD-INFO. 
15 OCRH-FIELD-STATUS PIC 9 
88 OCRH-FIELD-GCCD 
88 OCRH-FIELD-REJECT-CHARS 
88 OCRH-FIELD-WRONG-LENGTH 
OCRH-FIELD-CCKBINED-ERR 
OCRH-FIELD-BIANK 
88 OCRri-FIELD-BlAKK-SUP 
OCR-DATA-RECORD . 
10 OCR-STANDARD-MODE-RECORD 

15 OCR-STANDARD-FIELD-CHAR PIC 
10 OCR-IMAGE-MODE-RECORD 

REDEFINES OCR-STANDARD-MODE-RECORD. 
15 OCR-IMAGE-FIELE-LENGTH PIC 99 OCCURS 
15 OCR-IMAGE-FIELD-CHAR PIC X OCCURS 
********** END OF 3886 DATA DIVISION COPY MEMBER ************* 
05 NOTICE-OF-PAYMENT-DUE REDEFINES OCR-DATA -RECORD. 
10 LINE-1. 

15 Ll-POLICYHOLDER-NAME 

15 FILLER PIC X(15) . 

LINE-2 REDEFI -ES LINE-1. 

15 L2-CITY-AND-STATE 

15 L2-P0LICY-NU^EER 

15 L2-AM0UNT-DUE 

15 L2-PAYMENT-VEEIFY-C0DE 

LIKE-3 REDEFINES LINE-1. 

15 L3-AMCUNT-PAID PIC 9(5)V99. 



05 



OCCURS 130. 



14. 
102. 



10 



10 



PIC X(20) 



PIC X(20) . 
PIC X(8) . 
PIC 9(4)V99. 
PIC 9. 



90037000 
90047000 
90057000 
90067000 
90069000 
90C77C00 
90087000 
90097000 
90107000 
90117000 
90127000 
90137C00 
90147000 
90157000 
90167000 
90177000 
90187000 
90197000 
90217000 
90227000 

.90257000 
90267000 
90277000 
90287000 
90297000 
90307000 
90317000 

,90317400 
90323000 
90325000 
90326000 
90326200 
90327000 
90337000 
90347000 
90357000 
90367000 
90377000 
90387000 
90397000 
90407000 
90417000 
90427000 
90437000 
90447C00 
90457000 
90467000 
90477000 
90487000 
90497000 
90507000 
90517000 
90527000 
90537000 
90547000 
90557000 
90567000 
90577000 
90587000 
90597000 
90607000 
90617000 
90627000 
90637000 
90647000 
9065/UOO 
90667000 
90677000 
90687C00 
90697000 
90699CG0 
91561400 
91561600 
91561800 

91561900 
91562200 
91562400 
91562600 
91562700 
91562800 
91563100 



Figure 69. Sample OCR Program (Part 2 of 5) 
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00123 
00124 
00125 
00126 
00127 
00128 
00129 
00130 
00131 
00132 
00133 
00134 
00135 
00136 
00137 
00138 
00139 

nni fi n 

00141 
00142 
00143 
00144 
00145 
00146 
00147 
00148 
00149 
00150 
00151 
00152 
00153 
00154 
00155 
00156 
00157 
00158 
00159 
00160 
00161 
00162 
00163 
00164 
00165 
00166 
00167 
00168 
C0169 
00170 
00171 
00172 
00173 
00174 
00175 
00176 
00177 
00178 
00179 
00180 
00181 
00182 
00183 
00184 
00185 
00186 
00187 
00188 
00189 
00190 
00191 
00192 



GO TO PIO-EOP-ERR. 
60 TO PIO-GOOD. 
GO TO PlO-GOOD. 



PROCEDURE DIVISION. 

STOP RDN- 
PIO-START. 

MOVE 'SYSOIO' TO OCR-FILE-ID. 

MOVE 'FORMAT' TO OCR-FORMAT-RECORD-ID 

PERFORM OCR-OPEN. 

OPEN OUTPUT PRINTER. 
PIO-HEAD. 

MOVE ALL '*' TO PRINT-LINE. 

PERFORM PRINT-ROUTINE. 

MOVE 1 TO OCR-STACKER. 
PIO-READ. 

PERFORM OCR-READ. 

IF CCRS-NONRECOVERY-ERROR , 

IF OCRH-LINE-GOOD, 

IF OCRH-LINE-BLANK, 

IF CCRH-LINE-NCN-CRITICAL-ERR, GO TO PIO-GOOD. 

IF OCRH-END-OF-PAGE GO TO PIO-EOP, 

***** XF OCRH HAS ANY OTHER CODE, CONSIDER TEE DATA AS BAD **** 
PIO-BAD. 

MOVE MSG-EAD-DATA TO PRINT-LINE. 

PERFORM PRINT-ROUTINE . 

MOVE 2 TO OCR-STACKER. 
PIO-GOOD. 

MOVE OCR-DATA-RECORD TO PRINT-LINE. 

PERFORiM PRINT-ROUTINE. 

MOVE 1 TO PRINT-CONTROL. 

ADD 1 TO OCR-LINE-NUMBER, OCR-LINE- FORMAT. 

IF OCRH-LINE-NUMBER IS LESS THAN 3, GO TO PlO-SEAB. 
PIO-EOP. 

MOVE 3 TO OCR-LINE-NUMBER. 

PERFORI-'i OCR- EJECT. 
PIO-EOP-ERR. 

MOVE 1 TO CCR-LINE-NUMEER, OCR-LINE-FORMAT. 

MOVE 3 TO PRINT-CONTROL. 

GO TO PlO-hEAD. 
********* EXCEPTION PROCESSING ROUTINE *+**♦♦+******** 
OCR- EXCEPTION- ROUTINE . 

IF OCRS-END-OF-FILE, GO TO P20-EOF. 

IF CCRS-MARK-CHECK, 

MOVE MSG-MARK-CHECK TO PRINT-LINE, 
GO TO P20-RETURN. 

IF CCRS-NONRECOVERY-ERROR, 

MOVE MSG-NCNRECOVERY-ERROR TO PRINT-LINE, 
GO TO P20-RETURN. 

IF OCRS-INCOMPLETE-SCAN, 

MOVE MSG- INCOMPLETE- SCAN TO PRINT-LINE, 
GO TO P20-RETURN. 

IF CCRS-MARK-AND-EQUIP-CHECK, 

MOVE MSG-MARK-AND-EQUIP-CHECK TO OCR-LINE, 
GO TO P20-PRIKT-EOF. 

IF OCRS-PERMANENT-ERROR, 

MOVE MSG-PERMANENT-ERROP TO PRINT-LINE, 
GO TO P20-PRINT-EOF. 
***** IF NONE OF THE ABOVE ERRORS, GIVE TERMINATION MESSAGE ***** 

MOVE OCR-STATUS-KEY TO MSG-TERM-STATUS-KEY. 

MOVE MSG-TERMINATION TO PRINT-LINE. 

GO TO P2 0-PRINT-EOF. 
P20-RETURN. 

PERFORM PRINT-ROUTINE. 

GO TO OCR-CALL-EXIT. 
P20-PRINT-EOF. 

PERFORM PRINT-ROUTINE. 
P20-EOF. 

PERFORM OCR-CLOSE. 

CLOSE PRINTER. 

STOP RUN. 
PRINT-ROUTINE. 

WRITE PRINT-RECORD AFTER ADVANCING PRINT-CONTROL. 
OCR-CCPIED-PRCCEDuRES» COPY ILBDOCRP- 



S1563400 
91563700 
91564000 
91565000 
91566000 
91567000 
91568000 
91569000 
91570000 
91571000 
91572000 
91573000 
91574000 
91574200 
91575000 
91576000 
91579000 
91580000 
91581000 
91582000 
91583000 
91584000 
91584200 
91585000 
91585200 
91585400 
91585600 
91585800 
91585900 
91586200 
91586300 
91586400 
91586600 
91586700 
91586800 
91587100 
91587300 
91587400 
91587600 
91587700 
91587800 
91587900 
91588100 
91588500 
91588700 
91588900 
91589100 
91589300 
91589500 
91589700 
91590000 
91591000 
91592000 
91593000 
91594C0O 
91595000 
91596000 
91597000 
91598C00 
91598200 
91598400 
91600000 
91t301000 
91602000 
91603000 
91604000 
91605000 
91607000 
91609000 
91610000 



Figure 69. Sample OCR Program (Part 3 of 5) 
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00193 
0019H 
00195 
00196 
00197 
00198 
00199 
00200 
00201 
00202 
00203 
00201 
00205 
00206 
00207 
00208 
00209 
00210 
00211 
00212 
00213 
00214 
00215 
00216 
00217 
00218 
00219 
00220 
00221 
00222 
00223 
00224 
00225 
00226 
00227 
00228 
00229 
00230 
00231 
00232 
00233 
0023U 
00235 
00236 
00237 
00238 
00239 
00240 
00241 
00242 
00243 
00244 
00245 
00246 



4t****«:|.* OCR 3886 PROCEDURES ****♦♦♦♦♦ 
******tiif*^L^i^it ******************************************* ********** 

* THE 3886 OCR SUBROUTINE USES OCR-FILE FIELDS AS FOLLOWS 

* 

* ALL OPERATIONS REQUIRE 

* OCR-FILE-ID = THE UNIQUE NAKE USED TO IDENTIFY THE FILE 

* TO THE SUBROUTINE AND TO THE SYSTEM 

* OCR-OPERATION = THE CODE FOR THE REQUESTED OPERATION 

* ALL OPERATIONS RETURN 

* OCR-STATUS-KEY = RETURN CODE FOR VARIOUS OCCURRENCES 
* 

* OCR-OPEN ('OPEN ') ALSO REQUIRES 

* OCR- FORMAT-RECORD- ID = LIBRARY NAME OF DFR TO LOAD 

* OCR-CLOSE ('CLOSE') REQUIRES NO ADDITIONAL PARAMETERS 

* OCR- READ ('READ ') ALSO REQUIRES 

* OCR- LINE-NUMBER (1-33) = LINE TO READ (ON DOCUMENT) 

* OCR-LINE-FORKAT (1-63) = DLINT NUMBER (IN CURRENT DFR) 

* AND RETURNS (IF OCRS- SUCCESSFUL) 

* OCR- HEADER-RECORD = HEADER RECORD, AS RETURNED BY THE 3886 

* OCR-DATA-RECORD = DATA FROM DOCUMENT, FROM 3886 

* OCR- READ-OVERLAPPED CREADO') HAS SAKE REQUIREMENTS AS OCR-READ 

* OCR-WAIT ('WAIT ') RETURNS SAME PARAMETERS AS OCR-READ 

* OCR-MARK-LINE CMARKL') ALSO REQUIRES 

* OCR-LINE-NUMBER (1-33) = LINE TO MARK (ON DOCUMENT) 

* CCR-MARK (1-15) = SUM OF DESIRED MARK CODES (8421) 

* OCR- MARK- DOCUMENT CMARKD') ALSO REQUIRES 

* OCR-MARK (1-15) = SUM OF DESIRED MARK CODES (8421) 

* OCR- EJECT ('EJECT') ALSO REQUIRES 

* OCR- STACKER (1-2) = STACKER TO SELECT (A OR B) 

* OCR-LINE-NUMBER (0-33) = NUMBER OF LINES ON DOCUMENT 

* FOR VALIDATION (IF 0, NO VALIDATION WILL OCCUR) 

* OCR-SET-DEVICE CSETDV) ALSO REQUIRES 

* OCR-FORMAT-RECORD- ID = LIBRARY NAME OF DFR TO LOAD 
* 

♦NOTES- 

* 1. THE TERMS DFR AND DLINT ARE USED TO REFER TO THE EXPANDED 

* CODE, IN LOADABLE FORM, OF THE RESPECTIVE SYSTEM MACROS. 

* 2. OCR-WAIT MAY BE REQUESTED AFTER, AND ONLY AFTER, A 

* SUCCESSFUL OCR-READ-OVERLAPPED REQUEST. NO INTERVENING 

* I/O COMMANDS WILL BE ALLOWED OK THAT SAME FILE, 

* 3- THE PROCEDURES PROVIDED BELOW AUTOMATICALLY FILL IN 

* THE OCR-OPERATION FIELD, CALL THE SUBROUTINE, AND TEST 

* THE OCR- STATUS-KEY AFTER RETURN. IF ANY EXCEPTIONAL 

* CONDITIONS OCCUR, THEY PASS CONTROL TO THE ROUTINE 

* OCR- EXCEPTION-ROUTINE, WHICH THE PROGRAMMER MUST PROVIDE. 

* THE PROGRAMMER MAY AVOID EXCEPTION ROUTINE INVOCATION BY 

* ADDING THE FOLLOWING PHRASE TO THE COPY STATEMENT: 

* REPLACING OCR-EXCEPTION-ROUTINE BY OCR-CALL-EXIT 

* 4. ALTHOUGH OCR-STATUS-KEY MAY INDICATE THAT THE DESIRED 

* OPERATION WAS SUCCESSFUL, THE VALIDITY OF THE DATA OBTAINED 

* SHOULD BE DETERMINED BY TESTING CCRH- LINE-STATUS. 
**-tf^if^^-tft-*if*-^fif^^.if*t. *********************************************** 



90757000 
90767000 
90777000 
90778000 
90779000 
90780000 
90781000 
90782000 
90783000 
90784000 
90785000 
90786000 
90786200 
90786400 
90786600 
90786800 
90786900 
90787900 
90788100 
90788300 
90788500 
90788800 
90789800 
90790000 
90790200 
90790400 
90790600 
90790700 
90791700 
90791900 
90792100 
90792500 
90792600 
90793600 
90793800 
90794000 
90794200 
90794400 
90795300 
90795500 
90795700 
90795900 
90796100 
90796400 
90796600 
90796700 
90797900 
90798100 
90798300 



90798700 



Figure 69. Sample OCR Program (Part ^ of 



5) 
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002a7 
002H8 
00249 
00250 
00251 
00252 
00253 
00254 
00255 
00256 
00257 
00258 
00259 
00260 
00261 
00262 
00263 
00264 
00265 
00266 
00267 
00268 
00269 
00270 
00271 
00272 
00273 
00274 
00275 
00276 
0C277 
00278 
00279 
00280 



OCR-388 6-PROCEDURES. 90799700 

OCR-OPEN. 90800700 

MOVE 'OPEN • TO OCR-OFERATIOK OF OCR-FILE. 90807000 

PERFORM OCR-CALL THRU OCR-CALL-EXI'i. . 90817000 

OCR-CLOSE. 90827000 

^lOVE 'CLOSE* TO OCR-OPERATION OF OCR-FILE. 90837000 

PERFORM OCR-CALL THRU OCR-CALL-EXIT. 90847000 

OCR-READ. 90857000 

MOVE 'READ ' TO OCR-OPERATION CF OCR-FILE. 90867000 

PERFOPli OCR-CALL THRU OCR-CALL-EXIT. 90877000 

OCR- READ-OVERLAPPED. 90887000 

F.OVh 'READO' TO OCR-OPERATION CF OCR-FILE. 90897C00 

PERFORK OCR-CALL THRU OCR-CALL-EXIT. 90907000 

OCR-^vAIT. 90917C00 

KOVE 'WAIT • TO OCR-OPERATION OF OCR-FILE. 90927000 

PERFOR^i OCR-CALL THRU OCR-CALL-EXIT. 90937000 

OCR-i4ARK-LINE. 90947CC0 

MOVE 'MARKL' TO OCR-OPERATION CF OCR-FILE. 90957C00 

PERFORM OCR-CALL THRU OCR-CALL-EXIT. 90967000 

OCR-MARK-DOCUMENT. 90977CC0 

MOVE 'MARKD' TO OCR-OPERATION CF OCR-FILE. 90987C00 

PERFORM OCR-CALL THRU OCR-CALL-EXIT. 90997000 

OCR-EJECT. 91007000 

MOVE 'EJECT' TO OCR-OPERATION OF OCR-FILE- 91017000 

PERFORM OCR-CALL THRU OCR-CALL-EXIT. 91027000 

OCR-SET-DEVICE. 91037000 

MOVE 'SETDV TO OCR-OPERATION CF OCR-FILE- 91047000 

PERFORM OCR-CALL THRU OCR-CALL-EXIT. 91057000 

OCR-CALL- 91C67000 

CALL 'ILEDOCRO' USING OCR-FILE. 91077000 

IF NOT OCRS-SUCCESSFUL OF OCR-FILE, 91087000 

GO TO OCR-EXCEPTION-ROUTINE. 91097000 

OCR- CALL- EXIT. EXIT. 91107000 
**♦*♦****♦ END OF 3886 PROCEDURE DIVISION COPY MEMBER ********* 91109000 



Figure 69. Sample OCR Program (Part 5 of 5) 
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This index is supplemented with entries from the index of IBM DOS Full American National 
Standard COBOL . These entries are identified by an asterisk (*). 
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* 22,205,42 

* in arithmetic expressions* 

(see also asterisks, used in PICTURE 
clause) * 
** in arithmetic expressions* 
/* 15 
/& 15 

{ (see braces)* 
[ (see brackets)* 

(see pound sign)* 
. (see period)* 
... (see ellipsis)* 
< in relation conditions* 
( and ) in* 

arithmetic expressions* 

compound conditions* 

PICTURE clause* 

subscripting and indexing* 
+ (see plus symbol)* 

$ (see currency symbol, dollar sign)* 
; in Data Division and Procedure Division 
entries* 
(see also semicolon)* 
- (see either hyphen, or minus symbol)* 
/ in 

arithmetic expressions* 

sterling report items* 
, (see comma)* 
> in relation conditions* 
" in 

COMPUTE statement* 

relation conditions* 
■ or " in nonnumeric literals* 
(see also quotation- mark) * 



A, in PICTURE clause* 

alphabetic items* 

alphabetic symbol* 

alphanumeric edited items* 

alphanumeric items* 
abbreviations * 

abnormal termination 251-253 
absolute* 

column number* 

line spacing in a report* 

values in MOVE statement* 
ACCEPT statement 73,* 

subroutines 290 
Access Method Services 130 
ACCESS MODE and VSAM capabilities* 
ACCESS MODE clause* 
ACCESS MODE clause „ VSAM* 
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randomly 101 
sequentially 100 
accessing an indexed file 118-122,* 
randomly 121-122 
sequentially 121 
accessing a sequential file 99,* 
acknowledgement* 
action request time file status values 

(VSAM) 138 
ACTION statement 42 
actual decimal point* 
actual key 101-117 

actual track addressing 101-110, 
116-117 

considerations for specific 

devices 116-118 
sample program 106-110 
relative track addressing 101-106 

sample program 111-115 
structures 102 
ACTUAL KEY clause 101-102 

description and format 102,* 
READ statement* 
REWRITE statement* 
SEEK statement* 
WRITE statement* 
actual track addressing 101-110,116-117 
considerations for specific 

devices 116-118 
sample program 106-110 
ADCON table 298 

ADD Statement (Librarian) 51,52 
description and formats 51,* 
adding a record to a prime track 120 
adding records to an indexed file 119-120, 

121-122 
adding source statements to a book 51 
addition operator* 
addressing direct files 

actual track addressing 101-110, 
116-117 

sample program. 106-110 
relative track addressing 101-106 
sample program 111-115 
addressing schemes 99-122,* 
direct 99-117,* 
indexed 118-122,* 
sequential 99,* 
advantage of S-mode records over V-mode 

records 186 
algebraic value in a sign condition* 
algorithm* 

alignment of data items* 
comparisons* 
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decimal point* 

editing* 

File Section Items* 

JUSTIFIED clause* 

Linkage Section Items* 

PICTURE clause 196,* 

SYNCHRONIZED clause 200,* 

USING option* 

VALUE clause* 

Working- Storage Items 194,* 
ALL literal figurative constant* 

description* 

MOVE statement* 

relation condition* 

STOP statement* 
alphabetic character* 
alphabetic class test* 
alphabetic collating sequence* 
alphabetic data items* 
alphabetized cross-reference listing 

(SXREF) 37,36„67,* 
alphanumeric character* 
alphanumeric collating sequence* 
alphanumeric data item* 

allowable symbols* 

class test* 

description* 

internal representation* 

JUSTIFIED clause* 

MOVE statement 205,* 

relation condition* 

USAGE clause 197,* 

VALUE clause* 
alphanumeric edited character* 
alphanumeric edited item* 
alphanxameric literals* 
ALT parameter of ASSGN job control 

statement 25,24 
ALTER Statement 

in a called program 75 

in debug packets* 

description and format* 

effect on GO TO statement* 

segmentation* 

sort procedure* 
altering characters* 
altering execution sequence* 
altering usage of data items* 
alternative grouping of data* 

REDEFINES clause* 

RENAMES clause* 
amount of intermediate storage required for 

sort 208 
AND logical operator* 
APOST option 37 
apostrophe* 

application programs 12 
APPLY clause* 

CORE- INDEX option 101,99,* 

CYL-INDEX option 101,99,* 

CYL-OVERFLOW option 101,99,* 

EXTENDED- SEARCH option 101,99* 

MASTER-INDEX option 101,99,* 

WRITE-ONLY option 100,99,183,192,* 

programming technique* 

WRITE-VERIFY option 99,* 
arable numerals* 
Area A and Area B in reference format* 



arguments 

passed to a called assembler language 
program 7 9 

passed to a called COBOL program 76,77 
arithmetic expressions* 

characters used* 

COMPUTE statement 20U„+ 

conditions* 

description* 

evaluation rules* 
arithmetic operators* 
arithmetic statements* 

ADD* 

COMPUTE 204,* 

CORRESPONDING Option 205,* 

DIVIDE* 

GIVING option* 

intermediate results* 

MULTIPLY* 

overlapping operands* 

REMAINDER option* 

ROUNDED option* 

SIZE ERROR option* 

SUBTRACT* 
arithmetic subroutines 293 
ascending sequence* 

ASCII character set* 

EBCDIC character set* 

sort* 

table handling* 
ASCII considerations* 
ASCII subroutines 291 
ASCII tape files 177-178 
assembler language routine for 

accomplishing overlay 8 2 
assembler language subprograms 78-81 
assembler sublibrary of source statement 

library 48 
ASSGN control statement 24-25,20 
ASSIGN clause 24,19 

ASCII considerations* 

description and format 24,* 

NSTD-REELS special register 166,* 

sort* 

file in GIVING option* 
sort work units* 

system-name* 
ASSIGN clause, VSAM* 
assigning storage for compiler work file 

buffers 36 
assignment of input/output devices 19-20 
assumed* 

decimal point* 
description* 
numeric edited items* 
numeric items* 
sterling nonreport items* 

decimal scaling positions* 

pound and shilling separators* 
asterisk (*) 

arithmetic expressions* 

comments* 

in job deck 22 

in PHASE statement 42 

PICTURE clause* 

check protect symbol* 

numeric edited items* I 
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sterling report items* 
in source program 205 
AT END phrase* 

READ Statement* 

RETURN statement* 

SEARCH statement* 
AUTHOR paragraph* 
AUTOLINK feature 43 
Automatic Library Look-Up (AUTOLINK) 43 

and ACTION control statement 42,43 

and PHASE control statement 41,43 
auxiliary subroutines 291 



B, in PICTURE clause* 

alphanumeric edited items* 

numeric edited items* 

space symbol* 

sterling report items* 
background program 12 

label area 301 
BASIS card 57,48 

used for debugging 250 
batched- job mode 12 
BEFORE REPORTING declarative* 
binary collating sequence* 
binary data item 197-202,* 

in PICTURE clause 196,* 

description* 

intermediate results 203 

internal representation* 

MOVE Statement 205,* 

relation condition* 

SYNCHRONIZED clause 200„* 

USAGE clause 197,* 
BKEND control statement 4 9 
BLANK WHEN ZERO clause* 
BLOCK CONTAINS clause 194 

ASCII considerations* 

VSAM* 
block descriptor field 18 3 
block-length field 

V-mode records 18 
block prefix 177 

and BLOCK CONTAINS clause 194 
blocked records 180,181,* 

APPLY WRITE-ONLY clause* 

BLOCK CONTAINS clause 18 3,* 

inter-record slack bytes* 

recording mode* 
body print group* 
books in the source statement library 

cataloging 4 8-49 

retrieving 49 

updating 49-51 
boundary alignment* 
braces 22 

braces and brackets in formats* 
brackets 22,23 
BUF option 36 
buffer* 

allocation* 

ASCII considerations* 

combined function processing* 

offset 177 

truncation* 



buffer allocation VSAM* 
building tables 225 
bypassing label processing* 
byte„ contents of* 



C^ in sterling PICTURE* 
CALL Statement 75-76 

boundary alignment in* 

in segmented program 90 

3886 OCR processing* 
Called program 75 
calling an assembler language 

subprogram 78-82 
calling and called programs 7 5-87 
calling cataloged procedures 54 
calling program 75 
capacity records 99-100 
capitalized words in formats* 
carriage control character* 
CATAL option 33,45 
cataloged procedures, calling 54 
cataloging 

a book 48-49 

a module 46-47 

a program phase 45-46,40,41 

a segmented program 92 

a sort program 209 
CATALP control statement 53 
CATALR control statement 47-48 
CATALR option 39 
CATALS control statement 48-49 
CBL statement 36-39 
changing description of data items* 
changing installation defaults 39 
character set* 
character string* 
characters, significant for various 

options 39 
checking standard labels 162,174 

DLAB control statement 30 

DLBL control statement 28 

TLBL control statement 27 

TPLAB control statement 30 

VOL control statement 30 
check protect symbol* 

checkpoint/restart during a sort 210 
checkpoint subroutine 293 
checkpointing a COBOL program 262-263 
checkpoints during a sort operation 210 

control statement requirements 263 
CHKPT macro instruction 262 
class test subroutine 294 
classes of data* 
CLIST option 37 
CLOSE control statement 26 

description and format 26,* 

OPEN REVERSED Statement* 

random file options* 

sequential file options* 
CLOSE statement, VSAM* 
CLOSE UNIT subroutine 290 
CLOSE WITH LOCK subroutine 289 
COBOL execution output 72 
COBOL language usage with VSAM 141 
COBOL library subroutines 289-296 
COBOL option card (CBL card) 36-39 
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COBOL sublibrary of source statement 

library 48 
COBOL support for 3886 Optical Character 

Reader 320 
COBOL VSAM control blocks 14 5-149 
CODE clause* 

coding considerations for DOS/VS 191,* 
coding form, COBOL* 
collating sequence* 

ASCII* 

EBCDIC* 

for sort* 
COLUMN clause* 

combined function processing* 
comma, exchanging with period* 
comma* 

in editing* 

in statement formats 23 

PICTURE string* 

as punctuation* 
commands, job control 4 
comment control statement 22 
comments in job control statements 22 
comments on the phase map 71 
common exit point for . procedures* 
common processing facilities, VSAM* 

current record pointer* 

INTO/FROM identifier option* 

INVALID KEY condition* 

status key* 
Communication Region 3 01 

DATE control statement 26 
COMP items* 
COMP-1 items* 
COMP-2 items* 
COMP-3 items* 
COMP- 4 items* 
comparison* 

compare siobroutines 293 
compilation 17 

foreground 300,12 

job steps 13 

of copied text* 

of debugging packet* 

options for 36-38,32-33 

work files required for 297 
compile and edit job 14 
compile, edit, and execute job 14 
compile- only job 14 
compile-time debugging packet* 
compiler capacity 297-298 
compiler diagnostic messages 67 

generation of 260,307 

working with 260 
compiler directing statements* 

BASIS* 

COPY* 

DEBUG* 

description* 

DELETE* 

EJECT* 

ENTER* 

INSERT* 

list of* 

NOTE* 

SKIP* 
compiler -generated card number 

on diagnostic messages 67 



on object code listing 66 

on source statements 59 
compiler machine requirements 297 
compiler messages 67,260,307 
compiler options 

CBL card 36-39,59 

current-date* 

OPTION control statement 32-33 

quotation mark* 

sequence checking* 

truncation of binary items* 
compiler output 59-69 

from a segmented program 91 
compiler statistics 66 
compiler work files 297 
completion codes from sort program 2 09 
computational items 

conversions involving 197-200 

internal representation of 200-202 

special considerations for 200 
COMPUTATIONAL usage* 
COMPUTATIONAL- 1 items* 
COMPUTATIONAL- 1 usage* 
COMPUTATIONAL- 2 items* 
COMPUTATIONAL- 2 usage* 
COMPUTATIONAL- 3 items* 
COMPUTATIONAL- 3 usage* 
COMPUTATIONAL- 4 items* 
COMPUTATIONAL- 4 usage* 
COMPUTE Statement 

programming technique 204 

subroutines 293 
computer-name* 

OBJECT-COMPUTER paragraph* 

SOURCE-COMPUTER paragraph* 

System/370 instruction* 
COM- REG 301 

condensed object listing 37 
condition-name* 
condition- name condition* 
conditional sentence, definition* 
conditional statement* 
conditional variable* 
conditions* 

compound conditions* 

PERFORM statement* 

SEARCH statement* 

test conditions* 
Configuration Section* 

copying* 

description and format* 

OBJECT-COMPUTER paragraph* 

SOURCE- COMPUTER paragraph* 

SPECIAL-NAMES paragraph* 

and System/370 instruction generation* 
considerations when using overlay 

structures 81 
CONSOLE* 

ACCEPT Statement* 

DISPLAY statement* 

SPECIAL-NAMES paragraph* 
constant* 
continuation of 

job control statements 

DLAB control statement 30 
TPLAB control statement 30 

line-control cards 230 

program-control cards 230 
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control blocks, COBOL VSAM 145-149 
control breaks* 
control bytes* 

BLOCK CONTAINS clause* 

inter-record slack bytes* 

S-mode and V-mode records* 
control card, COBOL option 36 
CONTROL clause* 
control fields 

S-mode records 183,184 

V-mode records 180-181 
control footings and page format 214 
control hierarchy* 
control i^rof^ram 11 
CONTROL report group* 

CONTROL clause* 

GENERATE Statement* 

LINE clause* 

NEXT GROUP clause* 

PAGE LIMIT clause* 

report group description entry* 

summation* 

TYPE clause* 
controls in report writer* 
control sections 42 
control statement placement 

job control statements 23 

linkage editor control statements 41 

symbolic debug control 
statements 23 0-231 

UPDATE function 52 
conventional use of linkage registers 78 
conversion subroutines 291-292 
converting elementary data items 197-200 
converting non-VSAM files to VSAM 

files 144 
converting track addresses 

in a COBOL source program 

relative to actual 103,106 

in EXTENT control statement 
actual to relative 29 
relative to actual 29 
copy function of Librarian 45 
COPY statement 49 
copying* 

core image directory 45 
core image library 

private 55,18,32 

and Linkage Editor 40,300 

system 45-46 

and Linkage Editor 40,41 
CORE-INDEX option of the APPLY clause* 
correspondence of arguments and parameters 

assembler language subprograms 79 

COBOL subprograms 77 
CORRESPONDING option* 
counter updating* 
CR, in PICTURE clause* 
creating a direct file 101 

actual track addressing 101-110, 
116-117 

sample program 106-110 

relative track addressing 101-110 
sample program 111-115 

sample" job decks 304,303 
creating an indexed file 121 

sample job deck 305,303 



creating a VSAM file 

examples of 141-144 

language statements required for 141 
creating standard mass storage file 
labels 175,174 

DLAB control statement 30 

DLBL control statement 28 

PARSTD option 33 

STDLABEL option 33 
creating standard tape file 
labels 162,163-166 

PARSTD option 33 

STDLABEL option 33 

TLBL control statement 27 

TPLAB control statement 30 
creating user labels 162,165,174,175 

USRLABEL option 33 
credit symbol* 
cross-footing* 
cross-reference dictionary 67 

alphabetically ordered 37 

source ordered 33 
CSYNTAX option 38 
CURRENCY-SIGN clause* 

description and format* 

international considerations* 

restriction* 
currency symbol in PICTURE clause* 

dollar sign* 
description* 
numeric edited items* 

pound sign* 

(see also CURRENCY SIGN clause)* 
CURRENT-DATE 301,26 

current record pointer, VSAM 134 

cyclic check 288 ^ "" 

cylinder index 119 

cylinder overflow area 119 

CYL-INDEX option, APPLY clause* 

CYL-OVERFLOW option, APPLY clause* 

COl through Cl2 function-»names defined* 



D, in sterling PICTURE clause* 
D-mode records 177,18 
data, locating in a dump 253 
data access, VSAM 128 
data conversion 197-200,* 

DISPLAY statement 19a^l99,* 

EXAMINE statement* 

first character of program-name* 

GIVING option* 

MOVE Statement* 

TRANSFORM Statement* 
data description clauses* 

BLANK WHEN ZERO 

data-name* 

FILLER* 

JUSTIFIED* 

OCCURS* 

PICTURE 196,* 

REDEFINES 194, ♦ 

RENAMES* 

SYNCHRONIZED 200,* 

USAGE 197, * 

VALUE* 
data description entry* 
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Data Division* 

considerations for 3540 Diskette unit 
files 124 

considerations for VSAM* 
data extents 

direct files 28,30 

indexed files 28,30 
data files 15 

data flow logic in a CALL structure 78 
data format conversion 197-200 
data formats in the computer 200-202 
data item* 

data item alignment* 
data item description entry* 
data management 98,112 
data manipulation statements* 

EXAMINE* 

MOVE* 

TRANSFORM* 
data-name* 
data-name clause* 
data organization, VSAM 128,* 
DATA RECORDS clause* 
DATA RECORDS clause, VSAM 
data reference methods* 
data sets for symbolic debugging* 
data transformation* 
DATE-COMPILED 64 
DATE control statement 26 

and Communication Region 301 
DATE-WRITTEN paragraph* 
DEBUG card* 

debug control subroutine 294 
debug packet 250 

debugging language 229-232^247-251 
debugging TESTRUN 233 
decimal point alignment 196,* 

MOVE Statement 205,* 

period insertion character* 

rounding* 

size error* 
DECIMAL-POINT IS COMMA clause* 
DECK option 32 
declaratives* 

error processing* 

EXIT statement in* 

label handling* 

report writer* 

section* 

description and format* 

USE sentence* 
defaults* 

ACCESS MODE clause* 

APPLY CYL/MASTER- INDEX clause* 

BLOCK CONTAINS clause* 

changing 39 

cylinder overflow area* 

name- field in system-name* 

page format in Report Writer* 

printer spacing* 

priority number* 

quotation mark character* 

record size* 

recording mode* 

segment limit* 

sequence checking* 

truncation of binary items* 

USAGE clause* 



DEFINE command 130-134 

defining a VSAM data space: DEFINE 
SPACE 132 

defining a VSAM file: DEFINE 
CLUSTER 133 

defining a VSAM master catalog: DEFINE 
MASTERCATALOG 131 
Define The File (DTF) 98 
DEL Statement 51,52 
DELETE card 51-52 

used for copying 57,* 

used for debugging 250 
DELETE statement, VSAM 141,* 
deleting source statements 

for one run only 51 

from a book 48 
DEPENDING ON option of OCCURS clause 

and Table Handling Feature 217-223 

and variable-length records 218-220 
depth of a report page* 
descending sequence* 

in sort* 

in table handling* 
description and formats of job control 

statements 22-23 
DETAIL report group* 

description* 

GENERATE Statement* 

LINE clause* 

NEXT GROUP clause* 

SUM counters* 

TYPE clause* 
detailed file processing 

capabilities 145-176 
determining the location of the 

libraries 55 
determining the priority of the last 

segment loaded into the transient area 92 
device assignment 19-20 

duration of effect 24 
device support, VSAM 130 
diagnostic messages 

compiler 67,260,307 

execution-time 261 

Federal Information Processing Standard 
(FIPS) 68 

generation of 260 

linkage editor 71,261 

object time 309-317,260-261 

operator 307-309,73,72 

sort 209 
direct data organization 97,* 
direct files 99-118,97 

accessing techniques 100^101,* 

ACTUAL KEY clause 101„ * 

actual track addressing 101-110, 
116-117 

APPLY EXTENDED- SEARCH clause 101,* 

ASSIGN clause 100,101„* 

BLOCK CONTAINS clause* 

error processing 106,111„* 

initiating access 100,* 

invalid key condition* 

random access 101,* 

READ statement* 

recording mode* 

relative track addressing 101-106, I 
111-115 ^ 
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REWRITE Statement* 

sample job decks 304,303 

sequential access 100,* 

user labels* 

WRITE statement* 
direct indexing* 
direct linkage 8 2 

direct organization (DTFDA) 99-118,97 
disk extent subroutines 290 
Diskette input/output unit (3540) 

processing 123-125 
DISPLAY items 

conversions involving 197-200 

internal format of 201 

special considerations for 200 
DISPLAY statement* 
DISPLAY usage* 

alignment* 

alphabetic items* 

alphanumeric items* 

ASCII considerations* 

description* 

edited items* 

numeric items* 

SYNCHRONIZED clause* 
DISPLAY- ST usage* 

DISPLAY statement subroutines 290 
displaying data values during 

execution 248 
DIVIDE statement* 
division, arithmetic operation* 
division by zero* 
division header* 
division operator* 

division of a program, definition* 
division/remainder method of 
randomizing 103-106 

used to create a direct file 

actual track addressing 107-110 
relative track addressing 112-114 
DLAB control statement 30 
DLBL control statement 28 

identifying private libraries 55 
document description (OCR) 320 
dociiment design (OCR) 319 
dollar sign* 
DOS/VS COBOL Unresolved External 

References 71 
double slash 22 
double spacing* 
doubleword* 
DTF 

creation of 98,150 

locating in a dump 252-253 
DTF tables 150-155 
dummy files* 
dummy segment 8 9 
DUMP option 32 
dumps 

errors that can cause 252 

how to use 251 

symbolic 229-245 

system 251-259 
duplication of names* 



E, in 

external floating-point items* 
floating-point numeric literals* 

EBCDIC collating sequence (Extended Binary 
Coded Decimal Interchange Code)* 

edit and execute job 14 

editing 17-18, 40-42„* 

editing character* 

edit-only job 14 

editor, linkage 11 

effective storage considerations 298 

EJECT 59, 191, 325„* 

ellipsis 23 

tiiJ-ipti J.t> \...y xii i-OrTTicitS Z5f- 

ELSE option* 

IF statement* 

nested IF statements* 

ON statement* 
END DECLARATIVES.* 
END statement 51„ 52 
end-of-data control statement 15 
end of file* 

end-of-job control statement 15 
end of page condition* 
end of volume positioning* 
ENTER Statement* 
ENTRY control statement 42 
entry point in a called program 76,77 
entry-sequenced files 127 

considerations for READ statement 14 

considerations for REWRITE 
statement 139 

considerations for WRITE statement 139 
ENTRY statement 76 

in an overlay structure 83 
Environment Division* 

ASCII considerations* 

Configuration Section* 

Input-Output Section* 

international considerations* 

organization* 

segmentation considerations* 

sort considerations* 

System/370 card devices* 

System/37 instructions* 

354 Diskette unit file 
considerations 123 
equal sign (=)* 

in COMPUTE statement* 

in relation condition* 
equal size operands in a relation 

condition* 
equivalents* 

reserved words and abbreviations* 

THROUGH and THRU* 
error bytes* 

error conditions, arithmetic operations* 
error handling (VSAM) 36 

file status values 
at OPEN 138 
at action request time 138 

status key 136,130 
error messages, diagnostic (see messages) 
error message subroutine 295 
ERROR procedures, VSAM* 
error processing declaratives* 
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error recovery for non-VSAM files 155 

on unit-record devices 35 

using an assembler language 
routine 159-161 

using error declarative section 155-15! 

using INVALID KEY 155,156 
errors that can cause a dump 252 
ERRS option 33 
evaluation rules* 
EXAMINE Statement* 
EXCEPTION/ERROR procedure, VSAM* 

CLOSE statement* 

DELETE statement* 

description and format* 

OPEN statement* 

READ statement* 

REWRITE statement* 

START statement* 

WRITE statement* 
EXEC control statement 15 
EXEC FCOBOL Statement 17,15 
EXEC LNKEDT Statement 17,15 
execute-only job 14 
execution, order of* 
execution output 72-73 
execution time 

considerations 299-300 

machine requirements 297-298 

messages 261 
EXHIBIT statement 248-249,247 

subroutine 290 
exit point for procedures* 
EXIT PROGRAM Statement 76 

symbolic debugging* 
EXIT Statement* 

description and format* 

PERFORM statement* 

PROGRAM option* 

with sort procedures* 
explanatory comments* 
exponent* 

floating-point items* 

floating-point numeric literals* 
exponentiation 204 

Extended Binary Coded Decimal Interchange 
Code (EBCDIC)* 

collating sequence* 

nonnumeric literals* 
extended search 100 
EXTENDED- SEARCH Option of the APPLY 

clause 100,* 
extended source program library 

facility 57 
EXTENT control statement 28-30 
external data* 
external decimal items* 
external floating-point items* 
external-name 76 

in ASSIGN clause* 
external reference 71 

unresolved 71 

weak 71 



F-mode records 
FCOBOL 17 
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Features of the DOS/VS Compiler 7 

FD* 

Federal Information Processing Standard 

(FIPS) 39,* 
figurative constants* 
file* 

and volume portability (VSAM) 130 

definition* 

disposition of* 

CLOSE statement* 
OPEN statement* 

entry- sequenced 127 

FILE-CONTROL paragraph* 

file description entry* 

inter- record slack bytes* 

I-0-CONTROL paragraph* 

key- sequenced 127 
file control block (FCB) 148 
FILE-CONTROL paragraph* 

ACCESS MODE clause* 

ACTUAL KEY clause* 

ASSIGN clause* 

copying* 
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modularizing 202 

organization* 

Report Writer considerations* 

Sort considerations* 

statement list* 

statements 204-205,* 

sterling considerations* 

structure* 

table handling considerations* 

USING option on the division header* 
procedure library 53 
procedure-name 

arguments 79 

definition* 

table 298 
procedures, Declarati\'e* 
processing 3540 Diskette unit 
files 123-125 
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capabilities summary, VSAK* 

COBOL files on mass storage devices 

direct files 100-101 

indexed files 121 

programs 11 

sequential files 99 

ASCII tape files 177-178 

tapes from the 3886 OCR, Model 2 326 
PROCESSING MODE clause* 
Processor, Job Control 11,22 

options 32-33 
program, control 11 
program-control cards 231 
Program Global Table (PGT) 66 
PROGRAM-ID paragraph 

and program linkage 75-76 

and Segmentation 91-92 
Program Loader, Initial (IPL) 11 
program-name* 

program status, recording 262 
program switches 35 

Communication Region 301 
program termination* 

program versions, identification 247 
programmer logical units 19,20 
programming techniques 191-206 

Data -Division 193-202 

Environment Division 192 

general considerations 191 

Procedure Division 202-206 
programs 

application 12 

IBM- supplied 12 

processing 11 

system service 11 
PSERV, procedure library 54 
punctuation character* 
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listing* 
qualification* 

condition-names* 

description* 

index-names* 

names* 

subscripts* 
qualifier connective, definition* 
qualifier^ definition* 
quotation mark option* 

default* 

nonnumeric literals* 

program- name* 
QUOTE (QUOTES) figurative constant* 
QUOTE option 37 
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random access* 

ACCESS MODE clause* 
CLOSE statement* 
definition* 
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direct files 101,* 

error processing* 

indexed files 121-122,* 

READ statement* 

REWRITE statement* 

SEEK statement* 

WRITE statement* 
random file processing* 

effect of CLOSE options* 

function of a read* 
randomizing 

for the 2311 Disk Drive 116 

for the 2321 Data Cell Drive 117 
randomizing techniques 102-106 

sample programs 107-110„ 112-115 
range of a PERFORM statement* 
range of values* 

condition- name* 

priority numbers* 

sequence numbers on DELETE card* 
RCE (read column eliminate) processing* 
RD* 

READ INTO Statement 205 
READ NEXT Statement (VSAM) 140 
READ statement* 

description and format* 

error processing* 
READ Statement, VSAM 140,* 

description and formats* 

entry- sequenced file considerations 140 

key-sequenced file considerations 14 

processing capabilities* 
READ statement subroutines 289 
reading backwards* 
reading nonstandard labels* 
READY/RESET TRACE Statement* 
READY TRACE Statement 247-248 
receiving data item* 

justification* 

MOVE statement* 
record* 

description* 

level number* 

naming* 

slack bytes* 

RECORD CONTAINS clause 194 

description and format* 

Report Writer* 

Sort* 
RECORD CONTAINS clause, VSAM* 
record description (OCR) 320 
record description entry* 
record formats 179-18 8 

format F 179 

format S 183-188 

format U 18 

format V 180-183 

VSAM files 136 
RECORD KEY clause 122 
RECORD KEY clause, VSAM* 

description and format* 

START statement* 
record length for sort records* 
record size default* 

ACCEPT statement* 

DISPLAY statement* 
report writer* 
record zero (RO) 99 



recording capacities of mass storage 

devices 97 
recording mode* 

ASCII considerations* 

default* 

specification* 

types* 
RECORDING MODE clause 

description and format* 

ASCII considerations* 
RECORDING MODE clause invalid^ VSAM* 
recording program status 26 2 
REDEFINES clause 194,* 

APPLY CORE- INDEX option* 

description and format* 

position when used* 

SYNCHRONIZED clause* 

VALUE clause* 
redefining subscripts 194 
reference format* 

references, unresolved external 71 
register assignment 66 
register use for linkage 78 
regrouping data items* 
relation character* 
relation conditions* 
relational-operators* 
relationship of PICTURE to storage 

allocation 202 
relative indexing* 
relative LINE clause* 
RELEASE statement in sort* 
relocatable library 46-47 

cataloging a module 46 

directory 46 

INCLUDE statement 42 

maintenance functions 46 

private 42,43,55 
relocating loader feature 43 
relocation factor 39 
remainder, definition* 
REMARKS paragraph* 
RENAMES clause* 
renaming* 

data items* 

logical records* 
REP statement 51,52 
repitition of symbols in PICTURE* 
replacing source statements in a book 51 
REPORT clause 211 
REPORT clause invalid, VSAM* 
report, description* 
report description entry* 
report file, definition* 
REPORT FOOTING report group* 
report group description entry* 
report groups* 

REPORT HEADING report group* 
report page format effect on 

LINE-COUNTER special register* 

PAGE-COUNTER special register* 

PAGE LIMIT clause* 
Report Section* 

content* 

COPY statement* 

formats* 

structure* 

VALUE clause* 
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Report Writer Feature 211-215 

Data Division considerations* 

Procedure Division considerations* 
Report Writer routines, generation of 215 
report-name* 

Report Writer tables 299 
reposition tape subroutine 296 
required words for formats* 
RERUN clause 

ASCII considerations* 

and RSTRT control statement 262-263,34 

and Sort Feature 210 

subroutine 293 
RESERVE clause 192 
RESET control statement 34-35,25 
RESET TRACE Statement 248 
restarting a checkpointed 

program 262-263,34 
retrieving a book from the source statement 
library 4 9 

BASIS card 57 

COPY Statement 49,57 

modifying using INSERT and DELETE 
cards 57,58 
retrieving a direct file 100 

sample job deck 304 
retrieving an indexed file 121 

sample job deck 306 
retrieving a program phase 45-46 
retrieving a VSAM file 143 
return code* 

multi -volume files* 

sort* 
return from sort* 

input procedure* 

output procedure* 
RETURN statement in sort* 
reversed reading of a file* 
rewinding a tape file* 
REWRITE statement* 

description and format* 

error processing* 
REWRITE Statement, VSAM 139,* 

description and format* 

entry-sequenced file considerations 139 

key-sequenced file considerations 140 

processing capabilities* 
REWRITE statement subroutines 289 
rewriting mass storage files* 
right justification* 
rolling counters forward* 
root phase 18 

in overlay structure 81 
root phase overlay 18 
root segment 90,91,92 

including subprograms in 90 
ROUNDED option in arithmetic statements* 

ADD* 

COMPUTE* 

description* 

DIVIDE* 

MULTIPLY* 

SUBTRACT* 
rounding* 

RSTRT control statement 34,262-263 
rules for the SET statement 223 
RO (record zero) 99 



S, in PICTURE clause* 

S-mode records 183-18 8 

SAME clause* 

SAME Clause, VSAM* 

sample job decks 303-306 

sample label and file extent information 

for mass storage files 30 
sample linkage routines used with a calling 

subprogram 80 
sample linkage routines used with a lowest 

level subprogram 81 
sample logical unit assignments 20 
sample OCR program 327-331 
sample programs* 

creation of a direct file 106-115,* 

creation of an indexed file* 

OCR 327-331 

report writer* 

retrieval of a direct file* 

retrieval of an indexed file* 

sort* 

table handling* 
sample program output 265-278 
sample program with symbolic debugging 

features 235-246 
save area 79 

scaling, effect on rounding* 
scaling position character (P) * 
scientific decimal item* 
SEARCH ALL Statement 221 
SEARCH Statement 224-225 

subroutine 294 
section header* 
section-name* 
SEEK statement* 
segment classification 89,* 
segment descriptor field 184 
segment limit 91 
Segmentation Feature 89-94 

ALTER statement* 

called programs 90,* 

classifying segments 89,* 

control of 89„* 

fixed portion 91, * 

GO TO statement* 

independent segments 89,90,* 

operation 90 

output from a segmented program 91 

overlayable fixed segments 89,* 

PERFORM statement 93,* 

permanent segments 89,* 

priority numbers 8 9,* 

program organization* 

restrictions on program flow* 

segment limit 89,* 

with sort 93 
segmentation subroutine 293 
segments 89-90 
SELECT clause 

ASSGN control statement 28 

COPY statement* 

DLBL control statement 28 

EXTENT control statement 28-30 

formats* 

GIVING option of SORT statement* 

programming technique 181 

TLBL control statement 27 

VOL control statement 30 
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SELECT OPTIONAL clause 24 
semicolon* 

data description entry* 

source program* 
sentence* 

conditional* 

description* 

termination* 
SEPARATE CHARACTER Option of SIGN clause* 
separately signed niomeric subroutine 291 
separator* 
SEQ option 36 

sequence-check source statements 36 
sequence checking compilation default* 
sequence-number- field for copying* 
sequence niiraber in a source program* 
sequence of job control statements 23 
sequential access 99,* 

ACCESS MODE clause 99,* 

ACTUAL KEY clause 101,* 

APPLY WRITE-ONLY clause* 

ASSIGN clause* 

description 99,* 

direct files 100,* 

indexed files 121,* 

NOMINAL KEY clause* 

recording mode* 

RECORDING MODE clause* 

RESERVE Clause* 

sequential files 97,99,* 

size of records* 
sequential data organization 97,* 
sequential disk and tape labels 

subroutines 28 9 
sequential files 97,99,* 
sequential roultivolume files 99,* 
sequential organization (DTFSD) 99,97 
serial search of a table* 
service function of Librarian 45 
service programs, system 11 
Services, Access Method 130 
SET command 26,59 
SET statement 221-222 

description and formats* 

rules for 223 

with index data items* 

with indexes* 
setting values for index-names* 
severity levels of diagnostic messages 67 
sharing storage between files* 
shilling representation* 
short-precision internal floating-point 

items* 
sign* 

class condition* 

internal representation* 

literals* 

MOVE statement* 

PICTURE clause* 

relation condition* 

SIGN clause* 

sign condition* 

sterling items* 

subscripts* 

unary operator* 
SIGN clause 196 

ASCII considerations* 

class condition* 
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sign condition* 
7-track tape, restriction when used as sort 

work files 208 
sign usage 196 
significant characters for various 

options 39 
simple insertion editing* 
single digit level number* 
single-program mode 12 
size considerations 297 

SIZE ERROR option in arithmetic statements* 
SKIPl 59^191 
SKIP2 59„191 
SKIP3 59„191 
slack bytes* 

slash ampersand (/g) 15 
slash asterisk (/*) 15 
sort diagnostic messages 209 
sort* 

ascending and descending sequence* 

ASCII considerations 178,* 

checkpoints* 

collating sequence* 

control of procedures* 

Data Division considerations* 

Environment Division considerations* 

file description entry* 

final phase* 

input phase* 

keys* 

modification of records* 

optimizing performance 208-209,* 

Procedure Division considerations* 

sample program* 

special registers 209,* 

work units* 
Sort/Merge Feature 207-210 

intermediate storage required 2 08 

linkage 209 

machine requirements 300 

in a multiphase environment 210 

in a segmented program 93 

obtaining an ASCII collating 
sequence 178 

performance, improving 208-209 

products 207 
sort-file* 

COPY statement* 

description entry* 

SELECT clause* 
sort input/output control statements 207 
sort/merge interface subroutine 293 
sort/merge job control requirements 2 07 
sort/merge work files 208 
sort keys,, restriction 207,178 
sort-option 208.1-208.4 
sorting an unlabeled tape file 306„303 

sample job deck 306 
SORT-RETURN 209 
sort special registers 209„* 
SORT statement* 

description and format* 

GIVING option 207,* 

INPUT PROCEDURE Option* 

OUTPUT PROCEDURE Option* i 

RELEASE Statement* * 

RETURN statement* 

USING option 2 07«* 
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SORTWKl, S0RTWK2 in sort* 
SOURCE clause* 
SOURCE-COMPUTER paragraph* 
source program* 
definition* 
reference format* 
size considerations* 
structure* 
source program library facility 49,* 
COPY statement 49,* 
extended 57,* 
BASIS 57„* 

DELETE and INSERT 57^ * 
source statement library 48-52 
cataloging a book 48 
directory 48 
maintenance functions 48 
updating books 50 
space allocation 

EXTENT control Statement 28-29 
XTENT control Statement 30 
SPACEn option 37 
space insertion* 

SPACE (SPACES) figurative constant* 
spacing of source program listing 191 
spanned records 183-18 8 

on directly organized files 187-188 
on sequentially organized files 185-186 
and Sort Feature 2 08 
special characters* 

CURRENCY-SIGN clause* 
in formats* 
special considerations when using overlay 

structures 81 
special insertion editing* 
special level numbers* 
special-names, definition* 
SPECIAL-NAMES paragraph* 
special registers* 
report writer* 
LINE-COUNTER* 
PAGE- COUNTER* 
PRINT- SWTICH* 
sort* 

SORT-CORE-SIZE* 
SORT-FILE-SIZE* 
SORT- MODE- SIZE* 
SORT-RETURN 209,* 
system* 

COM-REG 301,* 
CURRENT-DATE 301** 
NSTD-REELS 166,* 
TALLY* 

TIME-OF-DAY* 
specifications for the first eight bytes of 

the actual key 102 
stacked items in formats* 
standard data format* 
standard file labels 

example of multiple volume 

creation 166,168-169 
mass storage 174-175 

format 1 281-286 
tape 162,163-164,279-280 
STANDARD option of the LABEL RECORDS 

clause* 
standard sequential file* 
APPLY WRITE-ONLY clause* 
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BLOCK CONTAINS clause* 

definition* 

effect of CLOSE options* 

error declarative capabilities* 

labels* 

reading* 

recording mode* 

RESERVE clause* 

writing* 
standard system procedures* 

error routines* 

label handling* 
START statement 122 

description and format* 

error processing* 

indexed files* 

NOMINAL KEY* 
START Statement, VSAM 141,* 

description and format* 

processing capabilities* 
STATE option 

description 38,229 

restriction with OPT 38,37,229 

restriction with STXIT 38,37,229 

restriction with SYMDMP 38,229 
statement form.ats 

job control 22-23 

symbolic debug option 229 
statement number option (see STATE option) 
statement number subroutine 294 
statistics 66 
Status Key 

OCR 322,323 

VSAM 138-139,136^130 
STDLABEL Option 33 
Sterling currency* 
STOP RUN statement* 
STOP statement 72 

subroutines 290 
storage required for sort* 
structures of the actual key 102 
STXIT option 37 

restriction with SYNDMP 38,37 

restriction with STATE 38,37,229 
subordinate phases 18 
subprogram interface (OCR) 321 
subprogram linkage statements 75-77,* 

CALL 75,* 

ENTRY 76,* 

EXIT PROGRAM* 

GOBACK* 

STOP RUN* 

termination considerations* 

USING option* 
subprogram structures 75-87 
subroutines 289-296 
subscripts 217 

condition-name* 

description and formats* 

qualification* 

qualifier* 

redefining 194 

restrictions on use* 
substitution* 

comma for period* 

dollar sign* 
subtotaling in a report* 
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SUBTRACT Statement* 

CORRESPONDING option* 

description and formats* 

GIVING option* 

overlapping operands* 

ROUNDED option* 

SIZE ERROR option* 
subtraction operator* 
SUM clause* 
SUM counters 211 

definition* 

GENERATE Statement* 

INITIATE statement* 

RESET clause* 

resetting to zero* 
SUM routines 212-213 
summary reporting* 
summation in a report* 
summing techniques 211 
Supervisor 11 
SUPMAP option 36 
suppress spacing* 
suppressing messages 

FLAGE option 36 

NOERRS option 33 
suppression of* 

library entry listing* 

report group printing* 

sequence checking* 

spacing in WRITE statement* 

zeros in PICTURE clause* 
suppression and replacement editing* 
suppression symbols* 
switch-status condition* 

description and format* 

system-names* 
SXREF option 

description 37 

example 67 

suppressing 37 
SYM option 33 
symbol pairs* 

symbolic debug option (see SYMDMP option) 
symbolic debugging features 229-246 

FLOW option 229 

STATE option 229 

SYMDMP option 229-232 
symbolic debugging subroutines 295 
symbolic names 

of input/output devices 19,20^21 

of phases 42 
symbolic portion of ACTUAL KEY* 
symbols* 

arithmetic expressions* 

floating-point literals* 

PICTURE clause* 

relation conditions* 

sterling currency formats* 

used to define compiler-generated 
information 66 
SYMDMP option 

description 229-230,38 

restriction with NOLINK and NODECK 38 

restriction with OPT 37^229 

restriction with STATE 38 

restriction with STXIT 37,38,229 
SYNCHRONIZED clause 200 
synonyms 116 



syntax checking 191„247 
SYNTAX option 38 
syntax rules 

job control statements 22-23 

symbolic debug control statements 230 
SYSCLB 19,21^55 
SYSIN 19,21 
SYSIPT 19,21 
SYSLNK 19,21„40 
SYSLOG 19, 21 
SYSLST 19,21„59 
SYSOUT 19,21„24 
SYSPCH 19,21 
SYSRDR 19,21 

on same device as SYSIPT 15,17,19 
SYSRES 19,21„55 
SYSRLB 19,21„55 
SYSSLB 19, 21 „ 55 
system closing conventions* 
system and size considerations 297-300 
system libraries, relative location 56 
system logical units 19 
system message identification codes 73 
system-name* 

ASSIGN clause* 

RERUN clause* 

Sort Feature* 
system-name restriction for RERUN on a sort 

file 210 
system output 73 
system service programs 11-12 
system special registers* 
SYSOOO through SYS221 19,21 
SYS005 38,232,297 
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Table Handling Feature 217-225 

ascending/descending sequence* 

Data Division considerations* 

indexing 217,* 

Procedure Division considerations* 

sample program* 

subscripting 217„* 
tables 298-299 
taking a checkpoint 262 
TALLY special register* 

ACCEPT statement* 

description* 

DISPLAY statement* 

EXAMINE statement* 

SOURCE clause* 

subscript* 

SUM clause* 
tape device, error information* 
tape file labels 279-280 
tape pointer subroutine 290 
table and sequential disk labels 

subroutines 289 
Task Global Table (TGT) 6 5 
TERMINATE statement 
termination of* 

execution* 

main programs* 

report processing* 

sort processing* 

subprograms* 
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test conditions* 

testing a program selectively 250 

testing additions and changes to 

programs 250-251 
THEN 

used in IF statement* 

used in sentences* 
THRU reserved word* 

and PERFORM Statement* 

and THROUGH, equivalence of* 

and VALUE clause* 
TIME-OF-DAY special register* 
TLBL control statement 26 

standard tape file labels 163,164 
TPLAB control statement 30 
TRACE statement 247 
track 97 
track addresses, converting 

in a COBOL source program 

relative to actual 103,106 

in EXTENT control statement 
actual to relative 29 
relative to actual 29 
track addressing 99-100 

actual 101-110„ 116-117 
sample program 106-110 

relative 101-106 

sample program 111-115 
TRACK- AREA clause* 
track formats for direct-access storage 

devices 287-288 
track index 119 
trailer labels* 
transfer of control* 

ALTER statement* 

CALL statement* 

calling and called programs* 

DECLARATIVES* 

end of series of procedures* 

EXIT statement* 

GO TO statement* 

GO TO MORE LABELS* 

GOBACK statement* 

operating system* 

operator* 

PERFORM statement* 

RELEASE statement* 

RETURN statement* 

segments, among* 

SORT feature* 
TRANSFORM statement 206 

ASCII considerations* 

description and format* 

subroutine 294 
transient area 92 
transient subroutines 295-296 
translation from ASCII to EBCDIC 178 
transmission errors* 
triple spacing* 
TRUNC option 37 
truncation* 

alphabetic and alphanumeric items* 

arithmetic operations* 

of buffers* 

of COMPUTATIONAL items 37 

floating insertion editing* 

MOVE statement* 

numeric items* 



TYPE clause* 

type codes used in SYMDKP output 234 

types of jobs 14 



U-mode records 18 
undefined records 180 
unique names* 

indexing* 

qualification* 

subscripting* 
unit, definition* 

in formats* 

in storage* 
unit record volume* 

CLOSE options* 

description* 

error information* 

list* 
unlabeled files 175 

example of multifile voliome 
processing 166,168-169 

example of multivolume file 
creation 167,172-173 

sorting 306 \. 

unnumbered messages, COBOL object-time 317 
unresolved external references 71 
unsigned numeric operands* 

considered positive* 

relation condition* 

sign condition* 
unsigned items 196-197 
UPDATE function 50-53 

ADD statement 50,51,52 

control statement placement 52 

DEL statement 51 

END statement 51 

invalid operand defaults 52 

REP statement 51 

UPDATE statement 50-51 
UPDATE Statement 50-52 
updating a book in the source statement 

library 50-52 
updating a direct file 101 

sample job deck 304 
updating an indexed file 120,121 

sample job deck 306 
upper-case letters in statement formats 22 
UPSI byte 35 
UPSI control statement 35 

Communication Region 301 
UPSI switches 301 
UPSI;-0 through UPSI-7 35 
USAGE clause 197 

alteration by redefining* 

ASCII considerations* 

default* 

description and format* 

index data items* 

internal representations* 
use of coding form* 

use of symbolic debugging features 229 
USE Statement* 
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error processing* 
label processing* 
report writer* 
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use of SUM 211 
user-created libraries* 
user error procedures* 
user header label (UHD* 
user labels 

mass storage files 174,175 

tape files 162^165 
user program status indicator bits* 
user program switch indicators 301 
user standard labels 162 
USING option 

of CALL Statement 75 

of ENTRY statement 76 

on Procedure Division header 76 
using ISAM programs to process VSAM 

files 144 
using the Report Writer feature 211-216 
using the Segmentation feature 89 
using the Sort/Merge feature 207 
using the START verb (VSAM) 141 
USRLABEL option 33 
utility data sets 

required by compiler 297 

required by sort program 300,208 
UTL (user trailer label)* 



V, in PICTURE clause* 
V-mode records 180-18 3 
valid mass storage devices* 
VALUE clause* 

condition- names* 
description and formats* 
example* 

report writer data items* 
sterling items* 
VALUE OF clause* 

variable-length records 180-183 
variable length table* 
various options, significant characters 

for 39 
VERB option 39 

vertical positioning of a printed line* 
Virtual Storage Access Method (see VSAM) 
VSAM catalog 128 
VSAM messages 130 
VOL control statement 30 
volume and file portability (VSAM) 130 
volume labels 

mass storage 174 
tape 162 
volume positioning, CLOSE statement* 
volume switch* 
CLOSE options* 
label processing* 
READ statement* 
WRITE statement* 
VSAM (Virtual Storage Access 
Method) 127-144 

Access Method Services 130 
DEFINE command 130-131 

defining a VSAM data space: 

DEFINE SPACE 132 
defining a VSAM file: 

DEFINE CLUSTER 133 
defining a VSAM master catalog: 
DEFINE MASTERCATALOG 131-132 
functional commands 130 



catalog 128 

COBOL language usage with VSAM 141 
COBOL VSAM control blocks 145 
converting non-VSAM files to VSAM 

files 144 
creating a VSAM file 141 

examples of 141-144 

language statements required for 141 
current record pointer 134 
data access 128 
Data Division considerations* 
data organization 128„129 
DEFINE command 130-131 
DELETE statement 141 
device support 130 
entry-sequenced files 127-128 
error handling 136 

file status values 
at OPEN 138 

at action request time 138 
error processing 130 

status key 138-139,136,130 
file and volume portability 130 
file control block (FCB) 148 
FILE-CONTROL paragraph* 
file information block (FIB) 146 
file organization 127 
file processing techniques 134 
file status values 

at OPEN 138 

at action request time 138 
initial loading of records into a 

file 137 
I-0-CONTROL paragraph* 
job control language for a VST^ 

file 144 
key-sequenced files 127 
messages 130 
opening a VSAM file 137 
overall description* 
Procedure Division considerations* 
processing capabilities summary* 
reading records on a VSAM file 14 

entry-sequenced file considerations 
for the READ statement 140 

key-sequenced file considerations for 
the READ statement 140 

READ NEXT Statement 140 

READ Statement 141 
record formats for VSAM files 136 
retrieving a VSAM file 143 
rewriting records on a VSAM 
file 139-140 

entry-sequenced file considerations 
for the REWRITE statement 139-140 

key-sequenced file considerations for 
the REWRITE statement 140 
security 130 
service programs (Access Method 

Services) 130 
status key 138-139,136,130 
subroutines 290 
using ISAM programs to process VSAM 

files 144 
using the START verb 141 
valid mass storage devices* 
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writing records into a VSAM file 139 
entry- sequenced file considerations 

for the WRITE stateirient 139 
key-sequenced file considerations 

for the WRITE statement 139 



X, in PICTURE clause* 
XREF dictionary 67 
XREF option 33 

X'ss* parameter of ASSGN job control 
statement 

possible specifications for 25 
XTENT control statement 30 



weak external reference 71 
WHEN-COMPILED special register 26,7,* 
WITH CODE clause 213-214 
word* 

characters used in* 

continuation of* 

definition* 

separators* 

types* 
word boundary* 
work files 

required by compiler 297,38 

required by sort program 300,208 
Working-Storage Section 194,* 

boundary alignment* 

condition-name entries* 

content* 

COPY statement* 

data item description entry* 

formats* 

level-numbers in* 

locating in a dump 194 

naming data* 

record description entry* 

renaming entries in* 

structure* 

used in error processing* 

use of FILLER* 

values of items* 
Working-Storage Section and OCR processing* 
WRITE FROM Statement 205 
WRITE-ONLY option of APPLY clause* 
WRITE Statement* 

combined function processing* 

description and formats* 

error processing* 

multivolume sequential files* 

system-name organization field* 
WRITE statement, VSAM 139,* 

description and format* 

entry-sequenced file considerations 139 

key-sequenced file considerations 139 

processing capabilities* 
WRITE statement subroutines 289 
WRITE-VERIFY option of APPLY clause* 
writing user labels* 



Z, in PICTURE clause* 

ZERO (ZEROES, ZEROS) figurative constant* 

description* 

MOVE statement* 

relation condition* 

replacing numeric literal* 

TRANSFORM Statement* 
zero divisor* 
zero insertion* 
zero operand* 

DIVIDE statement* 

internal floating-point items* 

relation condition* 

sign condition* 
zero, simple insertion editing* 
zero suppression and replacement editing* 
zone bits, external decimal items* 
zoned decimal format* 
ZWE option 37 



01-49 level numbers* 
6j, in sterling PICTURE clause* 
66 level number* 
7„ in sterling PICTURE clause* 
77 level number* 

7-track tape, restriction when used as sort 
work files 208 

8, in sterling PICTURE clause* 
88 level number* 

9, in PICTURE clause* 
alphanumeric edited items* 
description* 

numeric edited items* 

niameric items* 

precedence* 

sterling items* 
2319, 3211, 3330, 3350, 3410, 3420, 3505, 

3525 support 7,* 
2560, 3504, 3881, 5425 support 7,* 
3203, 3340, 3540, 5203 processing 7,* 
3540 processing 123-125 
3886 processing (see Optical Character 
Reader) 
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International Business Machines Corporation 

Data Processing Division 

1133 Westchester Avenue, White Plains, N.Y. 10604 

IBM World Trade Americas/Far East Corporation 

Town of Mount Pleasant, Route 9, North Tarrytown, N.Y., U.S.A. 10591 

IBM World Trade Europe/Middle East/Africa Corporation 
360 Hamilton Avenue, White Plains, N.Y., U.S.A. 10601 
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